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 23 69 66 6e 64 65 66 20 53 51 ndif..#ifndef SQ
0710: 4c 49 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e LITE_API.# defin
0720: 65 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e e SQLITE_API.#en
0730: 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 dif.../*.** Thes
0740: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61 e no-op macros a
0750: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74 re used in front
0760: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74 of interfaces t
0770: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20 o mark those.**
0780: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69 interfaces as ei
0790: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20 ther deprecated
07a0: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e or experimental.
07b0: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f New applicatio
07c0: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 ns.** should not
07d0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20 use deprecated
07e0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65 interfaces - the
07f0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f y are support fo
0800: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 r backwards.** c
0810: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c ompatibility onl
0820: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 y. Application
0830: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62 writers should b
0840: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 e aware that.**
0850: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 experimental int
0860: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a erfaces are subj
0870: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e ect to change in
0880: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e point releases.
0890: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 .**.** These mac
08a0: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f ros used to reso
08b0: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b lve to various k
08c0: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 inds of compiler
08d0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 magic that.** w
08e0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61 ould generate wa
08f0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77 rning messages w
0900: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73 hen they were us
0910: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a ed. But that.**
0920: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 compiler magic
0930: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74 ended up generat
0940: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72 ing such a flurr
0950: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73 y of bug reports
0960: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65 .** that we have
0970: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 taken it all ou
0980: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 t and gone back
0990: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a to using simple.
09a0: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a ** noop macros..
09b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
09c0: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65 E_DEPRECATED.#de
09d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45 fine SQLITE_EXPE
09e0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 RIMENTAL../*.**
09f0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d Ensure these sym
0a00: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65 bols were not de
0a10: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72 fined by some pr
0a20: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69 evious header fi
0a30: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 le..*/.#ifdef SQ
0a40: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 LITE_VERSION.# u
0a50: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 ndef SQLITE_VERS
0a60: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 ION.#endif.#ifde
0a70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e f SQLITE_VERSION
0a80: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 _NUMBER.# undef
0a90: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e SQLITE_VERSION_N
0aa0: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a UMBER.#endif../*
0ab0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
0ac0: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 mpile-Time Libra
0ad0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 ry Version Numbe
0ae0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b rs.**.** ^(The [
0af0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 SQLITE_VERSION]
0b00: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d C preprocessor m
0b10: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 acro in the sqli
0b20: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 te3.h header.**
0b30: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73 evaluates to a s
0b40: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 tring literal th
0b50: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65 at is the SQLite
0b60: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a version in the.
0b70: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a ** format "X.Y.Z
0b80: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65 " where X is the
0b90: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e major version n
0ba0: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20 umber (always 3
0bb0: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 for.** SQLite3)
0bc0: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e and Y is the min
0bd0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 or version numbe
0be0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72 r and Z is the r
0bf0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e elease number.)^
0c00: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 .** ^(The [SQLIT
0c10: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 E_VERSION_NUMBER
0c20: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 ] C preprocessor
0c30: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 macro resolves
0c40: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a to an integer.**
0c50: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20 with the value
0c60: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31 (X*1000000 + Y*1
0c70: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58 000 + Z) where X
0c80: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 , Y, and Z are t
0c90: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 he same.** numbe
0ca0: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 rs used in [SQLI
0cb0: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a TE_VERSION].)^.*
0cc0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52 * The SQLITE_VER
0cd0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 SION_NUMBER for
0ce0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73 any given releas
0cf0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c e of SQLite will
0d00: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 also.** be larg
0d10: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65 er than the rele
0d20: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69 ase from which i
0d30: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45 t is derived. E
0d40: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 ither Y will.**
0d50: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 be held constant
0d60: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 and Z will be i
0d70: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c ncremented or el
0d80: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 se Y will be inc
0d90: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 remented.** and
0da0: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20 Z will be reset
0db0: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 to zero..**.** S
0dc0: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36 ince version 3.6
0dd0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72 .18, SQLite sour
0de0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e ce code has been
0df0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a stored in the.*
0e00: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a * <a href="http:
0e10: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d //www.fossil-scm
0e20: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f .org/">Fossil co
0e30: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 nfiguration mana
0e40: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d gement.** system
0e50: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49 </a>. ^The SQLI
0e60: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63 TE_SOURCE_ID mac
0e70: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a ro evaluates to.
0e80: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 ** a string whic
0e90: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70 h identifies a p
0ea0: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d articular check-
0eb0: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 in of SQLite.**
0ec0: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 within its confi
0ed0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d guration managem
0ee0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68 ent system. ^Th
0ef0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f e SQLITE_SOURCE_
0f00: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e ID.** string con
0f10: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61 tains the date a
0f20: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 nd time of the c
0f30: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e heck-in (UTC) an
0f40: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73 d an SHA1.** has
0f50: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20 h of the entire
0f60: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a source tree..**.
0f70: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
0f80: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e lite3_libversion
0f90: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
0fa0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 _libversion_numb
0fb0: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f er()], [sqlite3_
0fc0: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 sourceid()],.**
0fd0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 [sqlite_version(
0fe0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 )] and [sqlite_s
0ff0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a ource_id()]..*/.
1000: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 #define SQLITE_V
1010: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 33 ERSION "3
1020: 2e 37 2e 36 2e 33 22 0a 23 64 65 66 69 6e 65 20 .7.6.3".#define
1030: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e SQLITE_VERSION_N
1040: 55 4d 42 45 52 20 33 30 30 37 30 30 36 0a 23 64 UMBER 3007006.#d
1050: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 efine SQLITE_SOU
1060: 52 43 45 5f 49 44 20 20 20 20 20 20 22 32 30 31 RCE_ID "201
1070: 31 2d 30 35 2d 31 39 20 31 33 3a 32 36 3a 35 34 1-05-19 13:26:54
1080: 20 65 64 31 64 61 35 31 30 61 32 33 39 65 61 37 ed1da510a239ea7
1090: 36 37 61 30 31 64 63 33 33 32 62 36 36 37 31 31 67a01dc332b66711
10a0: 39 66 61 33 63 39 30 38 65 22 0a 0a 2f 2a 0a 2a 9fa3c908e"../*.*
10b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d * CAPI3REF: Run-
10c0: 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 Time Library Ver
10d0: 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 sion Numbers.**
10e0: 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 KEYWORDS: sqlite
10f0: 33 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 3_version, sqlit
1100: 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a e3_sourceid.**.*
1110: 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 * These interfac
1120: 65 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 es provide the s
1130: 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 ame information
1140: 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 as the [SQLITE_V
1150: 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c ERSION],.** [SQL
1160: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 ITE_VERSION_NUMB
1170: 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 ER], and [SQLITE
1180: 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 _SOURCE_ID] C pr
1190: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f eprocessor macro
11a0: 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 s.** but are ass
11b0: 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 ociated with the
11c0: 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 library instead
11d0: 20 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66 of the header f
11e0: 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 ile. ^(Cautious
11f0: 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 .** programmers
1200: 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 might include as
1210: 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 sert() statement
1220: 73 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 s in their appli
1230: 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 cation to.** ver
1240: 69 66 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 ify that values
1250: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 returned by thes
1260: 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 e interfaces mat
1270: 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e ch the macros in
1280: 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 .** the header,
1290: 61 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 and thus insure
12a0: 74 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 that the applica
12b0: 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 tion is.** compi
12c0: 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e led with matchin
12d0: 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 g library and he
12e0: 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a ader files..**.*
12f0: 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
1300: 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 re>.** assert( s
1310: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
1320: 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 n_number()==SQLI
1330: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 TE_VERSION_NUMBE
1340: 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 R );.** assert(
1350: 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 strcmp(sqlite3_s
1360: 6f 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 ourceid(),SQLITE
1370: 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 _SOURCE_ID)==0 )
1380: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 ;.** assert( str
1390: 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 cmp(sqlite3_libv
13a0: 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f ersion(),SQLITE_
13b0: 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a VERSION)==0 );.*
13c0: 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
13d0: 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 uote>)^.**.** ^T
13e0: 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 he sqlite3_versi
13f0: 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 on[] string cons
1400: 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 tant contains th
1410: 65 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 e text of [SQLIT
1420: 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 E_VERSION].** ma
1430: 63 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 cro. ^The sqlit
1440: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 e3_libversion()
1450: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
1460: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
1470: 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 e.** to the sqli
1480: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 te3_version[] st
1490: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 ring constant.
14a0: 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 The sqlite3_libv
14b0: 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 ersion().** func
14c0: 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 tion is provided
14d0: 20 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 for use in DLLs
14e0: 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 since DLL users
14f0: 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 usually do not
1500: 68 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 have.** direct a
1510: 63 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 ccess to string
1520: 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e constants within
1530: 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a the DLL. ^The.
1540: 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 ** sqlite3_libve
1550: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 rsion_number() f
1560: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
1570: 61 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c an integer equal
1580: 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 to.** [SQLITE_V
1590: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 ERSION_NUMBER].
15a0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f ^The sqlite3_so
15b0: 75 72 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f urceid() functio
15c0: 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 n returns .** a
15d0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 pointer to a str
15e0: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f ing constant who
15f0: 73 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 se value is the
1600: 73 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 same as the .**
1610: 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 [SQLITE_SOURCE_I
1620: 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f D] C preprocesso
1630: 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 r macro..**.** S
1640: 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
1650: 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 _version()] and
1660: 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 [sqlite_source_i
1670: 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f d()]..*/.SQLITE_
1680: 41 50 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52 API SQLITE_EXTER
1690: 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c N const char sql
16a0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a ite3_version[];.
16b0: 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
16c0: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c char *sqlite3_l
16d0: 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b ibversion(void);
16e0: 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
16f0: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
1700: 73 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a sourceid(void);.
1710: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
1720: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
1730: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a n_number(void);.
1740: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1750: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 Run-Time Librar
1760: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 y Compilation Op
1770: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 tions Diagnostic
1780: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c s.**.** ^The sql
1790: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 ite3_compileopti
17a0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 on_used() functi
17b0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 on returns 0 or
17c0: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 1 .** indicating
17d0: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65 whether the spe
17e0: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 cified option wa
17f0: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a s defined at .**
1800: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 compile time.
1810: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 ^The SQLITE_ pre
1820: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 fix may be omitt
1830: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 ed from the .**
1840: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 option name pass
1850: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ed to sqlite3_co
1860: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 mpileoption_used
1870: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 (). .**.** ^The
1880: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 sqlite3_compile
1890: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e option_get() fun
18a0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 ction allows ite
18b0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 rating.** over t
18c0: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f he list of optio
18d0: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66 ns that were def
18e0: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 ined at compile
18f0: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 time by.** retur
1900: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f ning the N-th co
1910: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f mpile time optio
1920: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e n string. ^If N
1930: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 is out of range
1940: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d ,.** sqlite3_com
1950: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 pileoption_get()
1960: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 returns a NULL
1970: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 pointer. ^The S
1980: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 QLITE_ .** prefi
1990: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f x is omitted fro
19a0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65 m any strings re
19b0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 turned by .** sq
19c0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 lite3_compileopt
19d0: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a ion_get()..**.**
19e0: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68 ^Support for th
19f0: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e e diagnostic fun
1a00: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 ctions sqlite3_c
1a10: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 ompileoption_use
1a20: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 d().** and sqlit
1a30: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e e3_compileoption
1a40: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d _get() may be om
1a50: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79 itted by specify
1a60: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c ing the .** [SQL
1a70: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 ITE_OMIT_COMPILE
1a80: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 OPTION_DIAGS] op
1a90: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 tion at compile
1aa0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 time..**.** See
1ab0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 also: SQL functi
1ac0: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 ons [sqlite_comp
1ad0: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 ileoption_used()
1ae0: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 ] and.** [sqlite
1af0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 _compileoption_g
1b00: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 et()] and the [c
1b10: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 ompile_options p
1b20: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 ragma]..*/.#ifnd
1b30: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 ef SQLITE_OMIT_C
1b40: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 OMPILEOPTION_DIA
1b50: 47 53 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e GS.SQLITE_API in
1b60: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c t sqlite3_compil
1b70: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e eoption_used(con
1b80: 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d st char *zOptNam
1b90: 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 e);.SQLITE_API c
1ba0: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
1bb0: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e e3_compileoption
1bc0: 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e _get(int N);.#en
1bd0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 dif../*.** CAPI3
1be0: 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 REF: Test To See
1bf0: 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 If The Library
1c00: 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a Is Threadsafe.**
1c10: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
1c20: 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75 _threadsafe() fu
1c30: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a nction returns z
1c40: 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 ero if and only
1c50: 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 if.** SQLite was
1c60: 20 63 6f 6d 70 69 6c 65 64 20 6d 75 74 65 78 69 compiled mutexi
1c70: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 ng code omitted
1c80: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 due to the.** [S
1c90: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
1ca0: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
1cb0: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 ption being set
1cc0: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 to 0..**.** SQLi
1cd0: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c te can be compil
1ce0: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f ed with or witho
1cf0: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 ut mutexes. Whe
1d00: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 n.** the [SQLITE
1d10: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 _THREADSAFE] C p
1d20: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 reprocessor macr
1d30: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 o is 1 or 2, mut
1d40: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 exes.** are enab
1d50: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 led and SQLite i
1d60: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 s threadsafe. W
1d70: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 hen the.** [SQLI
1d80: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d TE_THREADSAFE] m
1d90: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 acro is 0, .** t
1da0: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f he mutexes are o
1db0: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 mitted. Without
1dc0: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 the mutexes, it
1dd0: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 is not safe.**
1de0: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f to use SQLite co
1df0: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 ncurrently from
1e00: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 more than one th
1e10: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 read..**.** Enab
1e20: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 ling mutexes inc
1e30: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 urs a measurable
1e40: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e performance pen
1e50: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 alty..** So if s
1e60: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 peed is of utmos
1e70: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 t importance, it
1e80: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 makes sense to
1e90: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d disable.** the m
1ea0: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 utexes. But for
1eb0: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c maximum safety,
1ec0: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 mutexes should
1ed0: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e be enabled..** ^
1ee0: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 The default beha
1ef0: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 vior is for mute
1f00: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 xes to be enable
1f10: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e d..**.** This in
1f20: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 terface can be u
1f30: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 sed by an applic
1f40: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 ation to make su
1f50: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 re that the.** v
1f60: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 ersion of SQLite
1f70: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b that it is link
1f80: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 ing against was
1f90: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
1fa0: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 the desired set
1fb0: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c ting of the [SQL
1fc0: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 ITE_THREADSAFE]
1fd0: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 macro..**.** Thi
1fe0: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 s interface only
1ff0: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 reports on the
2000: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 compile-time mut
2010: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 ex setting.** of
2020: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
2030: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 EADSAFE] flag.
2040: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
2050: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 piled with.** SQ
2060: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
2070: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 1 or =2 then mut
2080: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 exes are enabled
2090: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a by default but.
20a0: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 ** can be fully
20b0: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 or partially dis
20c0: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 abled using a ca
20d0: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ll to [sqlite3_c
20e0: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 onfig()].** with
20f0: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 the verbs [SQLI
2100: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 TE_CONFIG_SINGLE
2110: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 THREAD], [SQLITE
2120: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 _CONFIG_MULTITHR
2130: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c EAD],.** or [SQL
2140: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 ITE_CONFIG_MUTEX
2150: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e ]. ^(The return
2160: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a value of the.**
2170: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 sqlite3_threads
2180: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73 afe() function s
2190: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f hows only the co
21a0: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69 mpile-time setti
21b0: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20 ng of.** thread
21c0: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20 safety, not any
21d0: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 run-time changes
21e0: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67 to that setting
21f0: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69 made by.** sqli
2200: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e te3_config(). In
2210: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 other words, th
2220: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 e return value f
2230: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65 rom sqlite3_thre
2240: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75 adsafe().** is u
2250: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c nchanged by call
2260: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e s to sqlite3_con
2270: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 fig().)^.**.** S
2280: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e ee the [threadin
2290: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 g mode] document
22a0: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 ation for additi
22b0: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
22c0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
22d0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 int sqlite3_thre
22e0: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f adsafe(void);../
22f0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
2300: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 atabase Connecti
2310: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 on Handle.** KEY
2320: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 WORDS: {database
2330: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 connection} {da
2340: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2350: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f ns}.**.** Each o
2360: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 pen SQLite datab
2370: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 ase is represent
2380: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 ed by a pointer
2390: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f to an instance o
23a0: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 f.** the opaque
23b0: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 structure named
23c0: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 "sqlite3". It i
23d0: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e s useful to thin
23e0: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a k of an sqlite3.
23f0: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e ** pointer as an
2400: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 object. The [s
2410: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 qlite3_open()],
2420: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 [sqlite3_open16(
2430: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 )], and.** [sqli
2440: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 te3_open_v2()] i
2450: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74 nterfaces are it
2460: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 s constructors,
2470: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f and [sqlite3_clo
2480: 73 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 se()].** is its
2490: 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65 destructor. The
24a0: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 re are many othe
24b0: 72 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 r interfaces (su
24c0: 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 ch as.** [sqlite
24d0: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 3_prepare_v2()],
24e0: 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
24f0: 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e _function()], an
2500: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 d.** [sqlite3_bu
2510: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f sy_timeout()] to
2520: 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 name but three)
2530: 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 that are method
2540: 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 s on an.** sqlit
2550: 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 e3 object..*/.ty
2560: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
2570: 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f ite3 sqlite3;../
2580: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 *.** CAPI3REF: 6
2590: 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 4-Bit Integer Ty
25a0: 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a pes.** KEYWORDS:
25b0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 sqlite_int64 sq
25c0: 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a lite_uint64.**.*
25d0: 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 * Because there
25e0: 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 is no cross-plat
25f0: 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 form way to spec
2600: 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 ify 64-bit integ
2610: 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 er types.** SQLi
2620: 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 te includes type
2630: 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 defs for 64-bit
2640: 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 signed and unsig
2650: 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a ned integers..**
2660: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
2670: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 int64 and sqlite
2680: 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 3_uint64 are the
2690: 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 preferred type
26a0: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 definitions..**
26b0: 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 The sqlite_int64
26c0: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 and sqlite_uint
26d0: 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 64 types are sup
26e0: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 ported for backw
26f0: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 ards.** compatib
2700: 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a ility only..**.*
2710: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 * ^The sqlite3_i
2720: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f nt64 and sqlite_
2730: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 int64 types can
2740: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 store integer va
2750: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 lues.** between
2760: 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 -922337203685477
2770: 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 5808 and +922337
2780: 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 2036854775807 in
2790: 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a clusive. ^The.*
27a0: 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 * sqlite3_uint64
27b0: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 and sqlite_uint
27c0: 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 64 types can sto
27d0: 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 re integer value
27e0: 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 s .** between 0
27f0: 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 and +18446744073
2800: 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 709551615 inclus
2810: 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 ive..*/.#ifdef S
2820: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 QLITE_INT64_TYPE
2830: 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 . typedef SQLIT
2840: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c E_INT64_TYPE sql
2850: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 ite_int64;. typ
2860: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 edef unsigned SQ
2870: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 LITE_INT64_TYPE
2880: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 sqlite_uint64;.#
2890: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 elif defined(_MS
28a0: 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 C_VER) || define
28b0: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a d(__BORLANDC__).
28c0: 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 typedef __int6
28d0: 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 4 sqlite_int64;.
28e0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e typedef unsign
28f0: 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 ed __int64 sqlit
2900: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a e_uint64;.#else.
2910: 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c typedef long l
2920: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 ong int sqlite_i
2930: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 nt64;. typedef
2940: 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f unsigned long lo
2950: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 ng int sqlite_ui
2960: 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 nt64;.#endif.typ
2970: 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 edef sqlite_int6
2980: 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 4 sqlite3_int64;
2990: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f .typedef sqlite_
29a0: 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 uint64 sqlite3_u
29b0: 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 int64;../*.** If
29c0: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 compiling for a
29d0: 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 processor that
29e0: 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 lacks floating p
29f0: 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a oint support,.**
2a00: 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 substitute inte
2a10: 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 ger for floating
2a20: 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 -point..*/.#ifde
2a30: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c f SQLITE_OMIT_FL
2a40: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 OATING_POINT.# d
2a50: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c efine double sql
2a60: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 ite3_int64.#endi
2a70: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 f../*.** CAPI3RE
2a80: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 F: Closing A Dat
2a90: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e abase Connection
2aa0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2ab0: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74 te3_close() rout
2ac0: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72 ine is the destr
2ad0: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 uctor for the [s
2ae0: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a qlite3] object..
2af0: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c ** ^Calls to sql
2b00: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74 ite3_close() ret
2b10: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 urn SQLITE_OK if
2b20: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f the [sqlite3] o
2b30: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63 bject is.** succ
2b40: 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79 essfully destroy
2b50: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 ed and all assoc
2b60: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20 iated resources
2b70: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e are deallocated.
2b80: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 .**.** Applicati
2b90: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65 ons must [sqlite
2ba0: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 3_finalize | fin
2bb0: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 alize] all [prep
2bc0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d ared statements]
2bd0: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 .** and [sqlite3
2be0: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c _blob_close | cl
2bf0: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 ose] all [BLOB h
2c00: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74 andles] associat
2c10: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b ed with.** the [
2c20: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 sqlite3] object
2c30: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 prior to attempt
2c40: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 ing to close the
2c50: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a object. ^If.**
2c60: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 sqlite3_close()
2c70: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 is called on a
2c80: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2c90: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c tion] that still
2ca0: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 has.** outstand
2cb0: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 ing [prepared st
2cc0: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c atements] or [BL
2cd0: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65 OB handles], the
2ce0: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20 n it returns.**
2cf0: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a SQLITE_BUSY..**.
2d00: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f ** ^If [sqlite3_
2d10: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f close()] is invo
2d20: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e ked while a tran
2d30: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c saction is open,
2d40: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74 .** the transact
2d50: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63 ion is automatic
2d60: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b ally rolled back
2d70: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 ..**.** The C pa
2d80: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
2d90: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75 te3_close(C)] mu
2da0: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e st be either a N
2db0: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f ULL.** pointer o
2dc0: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f r an [sqlite3] o
2dd0: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 bject pointer ob
2de0: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b tained.** from [
2df0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c sqlite3_open()],
2e00: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
2e10: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 ()], or.** [sqli
2e20: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 te3_open_v2()],
2e30: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 and not previous
2e40: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 ly closed..** ^C
2e50: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 alling sqlite3_c
2e60: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55 lose() with a NU
2e70: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d LL pointer argum
2e80: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72 ent is a .** har
2e90: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a mless no-op..*/.
2ea0: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
2eb0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c qlite3_close(sql
2ec0: 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ite3 *);../*.**
2ed0: 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 The type for a c
2ee0: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
2ef0: 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 ..** This is leg
2f00: 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 acy and deprecat
2f10: 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 ed. It is inclu
2f20: 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 ded for historic
2f30: 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c al.** compatibil
2f40: 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 ity and is not d
2f50: 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 ocumented..*/.ty
2f60: 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 pedef int (*sqli
2f70: 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f te3_callback)(vo
2f80: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 id*,int,char**,
2f90: 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 char**);../*.**
2fa0: 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 CAPI3REF: One-St
2fb0: 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74 69 ep Query Executi
2fc0: 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a on Interface.**.
2fd0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 ** The sqlite3_e
2fe0: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 xec() interface
2ff0: 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 is a convenience
3000: 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a wrapper around.
3010: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
3020: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 are_v2()], [sqli
3030: 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 te3_step()], and
3040: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
3050: 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 ze()],.** that a
3060: 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 llows an applica
3070: 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 tion to run mult
3080: 69 70 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 iple statements
3090: 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 of SQL.** withou
30a0: 74 20 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 t having to use
30b0: 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e a lot of C code.
30c0: 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c .**.** ^The sql
30d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 ite3_exec() inte
30e0: 72 66 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 rface runs zero
30f0: 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e or more UTF-8 en
3100: 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f coded,.** semico
3110: 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c lon-separate SQL
3120: 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 statements pass
3130: 65 64 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 ed into its 2nd
3140: 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 argument,.** in
3150: 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 the context of t
3160: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
3170: 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 nection] passed
3180: 69 6e 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a in as its 1st.**
3190: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 argument. ^If
31a0: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e the callback fun
31b0: 63 74 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 ction of the 3rd
31c0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 argument to.**
31d0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 sqlite3_exec() i
31e0: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e s not NULL, then
31f0: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 it is invoked f
3200: 6f 72 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 or each result r
3210: 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 ow.** coming out
3220: 20 6f 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 of the evaluate
3230: 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 d SQL statements
3240: 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 . ^The 4th argu
3250: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 6f 20 73 71 ment to.** to sq
3260: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 lite3_exec() is
3270: 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68 20 relayed through
3280: 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75 6d to the 1st argum
3290: 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63 ent of each.** c
32a0: 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74 69 allback invocati
32b0: 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c on. ^If the cal
32c0: 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f lback pointer to
32d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a sqlite3_exec().
32e0: 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e ** is NULL, then
32f0: 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 no callback is
3300: 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64 ever invoked and
3310: 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72 65 result rows are
3320: 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a .** ignored..**.
3330: 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 ** ^If an error
3340: 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76 61 occurs while eva
3350: 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20 luating the SQL
3360: 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 statements passe
3370: 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 d into.** sqlite
3380: 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20 65 3_exec(), then e
3390: 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 xecution of the
33a0: 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65 6e current statemen
33b0: 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73 t stops and.** s
33c0: 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65 6d ubsequent statem
33d0: 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65 64 ents are skipped
33e0: 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 . ^If the 5th p
33f0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
3400: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 te3_exec().** is
3410: 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61 not NULL then a
3420: 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 ny error message
3430: 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f is written into
3440: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 memory obtained
3450: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 .** from [sqlite
3460: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 3_malloc()] and
3470: 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f passed back thro
3480: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 ugh the 5th para
3490: 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f meter..** To avo
34a0: 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c id memory leaks,
34b0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
34c0: 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b should invoke [
34d0: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a sqlite3_free()].
34e0: 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73 ** on error mess
34f0: 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 age strings retu
3500: 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68 65 rned through the
3510: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 5th parameter o
3520: 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f f.** of sqlite3_
3530: 65 78 65 63 28 29 20 61 66 74 65 72 20 74 68 65 exec() after the
3540: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 error message s
3550: 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 tring is no long
3560: 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 er needed..** ^I
3570: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 f the 5th parame
3580: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 ter to sqlite3_e
3590: 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c xec() is not NUL
35a0: 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a L and no errors.
35b0: 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 ** occur, then s
35c0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73 65 qlite3_exec() se
35d0: 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69 ts the pointer i
35e0: 6e 20 69 74 73 20 35 74 68 20 70 61 72 61 6d 65 n its 5th parame
35f0: 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 ter to.** NULL b
3600: 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e efore returning.
3610: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 .**.** ^If an sq
3620: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c lite3_exec() cal
3630: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f lback returns no
3640: 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 n-zero, the sqli
3650: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f te3_exec().** ro
3660: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51 utine returns SQ
3670: 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f LITE_ABORT witho
3680: 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 ut invoking the
3690: 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 callback again a
36a0: 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 nd.** without ru
36b0: 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71 nning any subseq
36c0: 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 uent SQL stateme
36d0: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 nts..**.** ^The
36e0: 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 2nd argument to
36f0: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 the sqlite3_exec
3700: 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 () callback func
3710: 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e tion is the.** n
3720: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
3730: 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20 in the result.
3740: 20 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d 65 ^The 3rd argume
3750: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 nt to the sqlite
3760: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 3_exec().** call
3770: 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 back is an array
3780: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 of pointers to
3790: 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 strings obtained
37a0: 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b as if from.** [
37b0: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
37c0: 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 ext()], one for
37d0: 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 each column. ^I
37e0: 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 f an element of
37f0: 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 a.** result row
3800: 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 is NULL then the
3810: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 corresponding s
3820: 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f tring pointer fo
3830: 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 r the.** sqlite3
3840: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b _exec() callback
3850: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
3860: 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 er. ^The 4th ar
3870: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a gument to the.**
3880: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
3890: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 callback is an a
38a0: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 rray of pointers
38b0: 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72 to strings wher
38c0: 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 e each.** entry
38d0: 72 65 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e represents the n
38e0: 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e ame of correspon
38f0: 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 ding result colu
3900: 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a mn as obtained.*
3910: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f * from [sqlite3_
3920: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a column_name()]..
3930: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e **.** ^If the 2n
3940: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 d parameter to s
3950: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 qlite3_exec() is
3960: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
3970: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f a pointer.** to
3980: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 an empty string
3990: 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 , or a pointer t
39a0: 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c hat contains onl
39b0: 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 y whitespace and
39c0: 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d /or .** SQL comm
39d0: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 ents, then no SQ
39e0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 L statements are
39f0: 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74 evaluated and t
3a00: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 he database.** i
3a10: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a s not changed..*
3a20: 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e *.** Restriction
3a30: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a s:.**.** <ul>.**
3a40: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 <li> The applic
3a50: 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72 ation must insur
3a60: 65 20 74 68 61 74 20 74 68 65 20 31 73 74 20 70 e that the 1st p
3a70: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
3a80: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 te3_exec().**
3a90: 20 20 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e is a valid an
3aa0: 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 d open [database
3ab0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a connection]..**
3ac0: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 <li> The applic
3ad0: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 ation must not c
3ae0: 6c 6f 73 65 20 5b 64 61 74 61 62 61 73 65 20 63 lose [database c
3af0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 onnection] speci
3b00: 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 fied by.**
3b10: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 the 1st paramete
3b20: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 r to sqlite3_exe
3b30: 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 c() while sqlite
3b40: 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 3_exec() is runn
3b50: 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 ing..** <li> The
3b60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
3b70: 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 t not modify the
3b80: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
3b90: 65 78 74 20 70 61 73 73 65 64 20 69 6e 74 6f 0a ext passed into.
3ba0: 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e 64 20 ** the 2nd
3bb0: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c parameter of sql
3bc0: 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c ite3_exec() whil
3bd0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 e sqlite3_exec()
3be0: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 is running..**
3bf0: 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f </ul>.*/.SQLITE_
3c00: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
3c10: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a exec(. sqlite3*
3c20: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
3c30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3c40: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 /* An open da
3c50: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 tabase */. cons
3c60: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 t char *sql,
3c70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3c80: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f /* SQL to
3c90: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f be evaluated */
3ca0: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 . int (*callbac
3cb0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 k)(void*,int,cha
3cc0: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a r**,char**), /*
3cd0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 Callback functi
3ce0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 on */. void *,
3cf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3d00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3d10: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 /* 1st argume
3d20: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a nt to callback *
3d30: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 /. char **errms
3d40: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 g
3d50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
3d60: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 * Error msg writ
3d70: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a ten here */.);..
3d80: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
3d90: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 Result Codes.**
3da0: 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 KEYWORDS: SQLITE
3db0: 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d _OK {error code}
3dc0: 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a {error codes}.*
3dd0: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 * KEYWORDS: {res
3de0: 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c ult code} {resul
3df0: 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d t codes}.**.** M
3e00: 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 any SQLite funct
3e10: 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 ions return an i
3e20: 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f nteger result co
3e30: 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 de from the set
3e40: 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e shown.** here in
3e50: 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 order to indica
3e60: 74 65 73 20 73 75 63 63 65 73 73 20 6f 72 20 66 tes success or f
3e70: 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 ailure..**.** Ne
3e80: 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 w error codes ma
3e90: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 y be added in fu
3ea0: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 ture versions of
3eb0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 SQLite..**.** S
3ec0: 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 ee also: [SQLITE
3ed0: 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 _IOERR_READ | ex
3ee0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
3ef0: 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 des].*/.#define
3f00: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 SQLITE_OK
3f10: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 0 /* Succe
3f20: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a ssful result */.
3f30: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d /* beginning-of-
3f40: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 error-codes */.#
3f50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 define SQLITE_ER
3f60: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f ROR 1 /
3f70: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d * SQL error or m
3f80: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 issing database
3f90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
3fa0: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 E_INTERNAL 2
3fb0: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c /* Internal l
3fc0: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 ogic error in SQ
3fd0: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 Lite */.#define
3fe0: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 SQLITE_PERM
3ff0: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 3 /* Acces
4000: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e s permission den
4010: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ied */.#define S
4020: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 QLITE_ABORT
4030: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 4 /* Callba
4040: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 ck routine reque
4050: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f sted an abort */
4060: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4070: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20 BUSY 5
4080: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 /* The database
4090: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 file is locked
40a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
40b0: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 E_LOCKED 6
40c0: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e /* A table in
40d0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 the database is
40e0: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 locked */.#defi
40f0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 ne SQLITE_NOMEM
4100: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 7 /* A
4110: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 malloc() failed
4120: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4130: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 E_READONLY 8
4140: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f /* Attempt to
4150: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c write a readonl
4160: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 y database */.#d
4170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 efine SQLITE_INT
4180: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a ERRUPT 9 /*
4190: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 Operation termi
41a0: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 nated by sqlite3
41b0: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 _interrupt()*/.#
41c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
41d0: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f ERR 10 /
41e0: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 * Some kind of d
41f0: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 isk I/O error oc
4200: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e curred */.#defin
4210: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 e SQLITE_CORRUPT
4220: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 11 /* The
4230: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 database disk i
4240: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 mage is malforme
4250: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
4260: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 ITE_NOTFOUND
4270: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 12 /* Unknown
4280: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 opcode in sqlite
4290: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 3_file_control()
42a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
42b0: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 TE_FULL 1
42c0: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 3 /* Insertion
42d0: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 failed because
42e0: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c database is full
42f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4300: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 TE_CANTOPEN 1
4310: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 4 /* Unable to
4320: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 open the databa
4330: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 se file */.#defi
4340: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 ne SQLITE_PROTOC
4350: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 OL 15 /* Da
4360: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 tabase lock prot
4370: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 ocol error */.#d
4380: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 efine SQLITE_EMP
4390: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a TY 16 /*
43a0: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 Database is emp
43b0: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ty */.#define SQ
43c0: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 LITE_SCHEMA
43d0: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 17 /* The dat
43e0: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 abase schema cha
43f0: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 nged */.#define
4400: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 SQLITE_TOOBIG
4410: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 18 /* Strin
4420: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 g or BLOB exceed
4430: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a s size limit */.
4440: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
4450: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 ONSTRAINT 19
4460: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 /* Abort due to
4470: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 constraint viola
4480: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 tion */.#define
4490: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 SQLITE_MISMATCH
44a0: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 20 /* Data
44b0: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f type mismatch */
44c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
44d0: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 MISUSE 21
44e0: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 /* Library used
44f0: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a incorrectly */.
4500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e #define SQLITE_N
4510: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 OLFS 22
4520: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 /* Uses OS featu
4530: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 res not supporte
4540: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 d on host */.#de
4550: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 fine SQLITE_AUTH
4560: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 23 /*
4570: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 Authorization de
4580: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 nied */.#define
4590: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 SQLITE_FORMAT
45a0: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 24 /* Auxil
45b0: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f iary database fo
45c0: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 rmat error */.#d
45d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e efine SQLITE_RAN
45e0: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a GE 25 /*
45f0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 2nd parameter t
4600: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f o sqlite3_bind o
4610: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 ut of range */.#
4620: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f define SQLITE_NO
4630: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f TADB 26 /
4640: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 * File opened th
4650: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 at is not a data
4660: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 base file */.#de
4670: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 fine SQLITE_ROW
4680: 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 100 /*
4690: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 sqlite3_step() h
46a0: 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 as another row r
46b0: 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 eady */.#define
46c0: 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 SQLITE_DONE
46d0: 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 101 /* sqlit
46e0: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 e3_step() has fi
46f0: 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 nished executing
4700: 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 */./* end-of-er
4710: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a ror-codes */../*
4720: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 .** CAPI3REF: Ex
4730: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f tended Result Co
4740: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a des.** KEYWORDS:
4750: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 {extended error
4760: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 code} {extended
4770: 20 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a error codes}.**
4780: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 KEYWORDS: {exte
4790: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
47a0: 7d 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 } {extended resu
47b0: 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 lt codes}.**.**
47c0: 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 In its default c
47d0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 onfiguration, SQ
47e0: 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 Lite API routine
47f0: 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 s return one of
4800: 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 26 integer.** [S
4810: 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c QLITE_OK | resul
4820: 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 t codes]. Howev
4830: 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 er, experience h
4840: 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 as shown that ma
4850: 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 ny of.** these r
4860: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 esult codes are
4870: 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e too coarse-grain
4880: 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 ed. They do not
4890: 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d provide as.** m
48a0: 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 uch information
48b0: 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 about problems a
48c0: 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 s programmers mi
48d0: 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e ght like. In an
48e0: 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 effort to.** ad
48f0: 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 dress this, newe
4900: 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 r versions of SQ
4910: 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e Lite (version 3.
4920: 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 3.8 and later) i
4930: 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 nclude.** suppor
4940: 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c t for additional
4950: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 result codes th
4960: 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 at provide more
4970: 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 detailed informa
4980: 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 tion.** about er
4990: 72 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 rors. The extend
49a0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 ed result codes
49b0: 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 are enabled or d
49c0: 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 isabled.** on a
49d0: 70 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e per database con
49e0: 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 nection basis us
49f0: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 ing the.** [sqli
4a00: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 te3_extended_res
4a10: 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 ult_codes()] API
4a20: 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 ..**.** Some of
4a30: 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 the available ex
4a40: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
4a50: 64 65 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 des are listed h
4a60: 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 ere..** One may
4a70: 65 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 expect the numbe
4a80: 72 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 r of extended re
4a90: 73 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 sult codes will
4aa0: 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 be expand.** ove
4ab0: 72 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 r time. Softwar
4ac0: 65 20 74 68 61 74 20 75 73 65 73 20 65 78 74 65 e that uses exte
4ad0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
4ae0: 73 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a s should expect.
4af0: 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 ** to see new re
4b00: 73 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 sult codes in fu
4b10: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 ture releases of
4b20: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 SQLite..**.** T
4b30: 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 he SQLITE_OK res
4b40: 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 ult code will ne
4b50: 76 65 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e ver be extended.
4b60: 20 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 It will always
4b70: 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a .** be exactly z
4b80: 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ero..*/.#define
4b90: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 SQLITE_IOERR_REA
4ba0: 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 D (
4bb0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
4bc0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 1<<8)).#define S
4bd0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 QLITE_IOERR_SHOR
4be0: 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 T_READ (S
4bf0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 QLITE_IOERR | (2
4c00: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
4c10: 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 LITE_IOERR_WRITE
4c20: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
4c30: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c LITE_IOERR | (3<
4c40: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
4c50: 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 ITE_IOERR_FSYNC
4c60: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
4c70: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c ITE_IOERR | (4<<
4c80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4c90: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 TE_IOERR_DIR_FSY
4ca0: 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 NC (SQLI
4cb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 TE_IOERR | (5<<8
4cc0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
4cd0: 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 E_IOERR_TRUNCATE
4ce0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
4cf0: 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 E_IOERR | (6<<8)
4d00: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
4d10: 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 _IOERR_FSTAT
4d20: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
4d30: 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 _IOERR | (7<<8))
4d40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4d50: 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 IOERR_UNLOCK
4d60: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
4d70: 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a IOERR | (8<<8)).
4d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
4d90: 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 OERR_RDLOCK
4da0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
4db0: 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 OERR | (9<<8)).#
4dc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
4dd0: 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 ERR_DELETE
4de0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
4df0: 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 ERR | (10<<8)).#
4e00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
4e10: 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 ERR_BLOCKED
4e20: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
4e30: 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 ERR | (11<<8)).#
4e40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
4e50: 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 ERR_NOMEM
4e60: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
4e70: 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 ERR | (12<<8)).#
4e80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
4e90: 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 ERR_ACCESS
4ea0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
4eb0: 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 ERR | (13<<8)).#
4ec0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
4ed0: 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 ERR_CHECKRESERVE
4ee0: 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f DLOCK (SQLITE_IO
4ef0: 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 ERR | (14<<8)).#
4f00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
4f10: 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 ERR_LOCK
4f20: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
4f30: 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 ERR | (15<<8)).#
4f40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
4f50: 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 ERR_CLOSE
4f60: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
4f70: 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 ERR | (16<<8)).#
4f80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
4f90: 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 ERR_DIR_CLOSE
4fa0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
4fb0: 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 ERR | (17<<8)).#
4fc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
4fd0: 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 ERR_SHMOPEN
4fe0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
4ff0: 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 ERR | (18<<8)).#
5000: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
5010: 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 ERR_SHMSIZE
5020: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
5030: 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 ERR | (19<<8)).#
5040: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
5050: 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 ERR_SHMLOCK
5060: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
5070: 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 ERR | (20<<8)).#
5080: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f define SQLITE_LO
5090: 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 CKED_SHAREDCACHE
50a0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f (SQLITE_LO
50b0: 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a CKED | (1<<8)).
50c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 #define SQLITE_B
50d0: 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 USY_RECOVERY
50e0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 (SQLITE_B
50f0: 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 USY | (1<<8))
5100: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5110: 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 CANTOPEN_NOTEMPD
5120: 49 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f IR (SQLITE_
5130: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 CANTOPEN | (1<<8
5140: 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 ))../*.** CAPI3R
5150: 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 EF: Flags For Fi
5160: 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f le Open Operatio
5170: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 ns.**.** These b
5180: 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e it values are in
5190: 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 tended for use i
51a0: 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 n the.** 3rd par
51b0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 ameter to the [s
51c0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
51d0: 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a ] interface and.
51e0: 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 ** in the 4th pa
51f0: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 78 rameter to the x
5200: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 Open method of t
5210: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 he.** [sqlite3_v
5220: 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 fs] object..*/.#
5230: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
5240: 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 EN_READONLY
5250: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 20 20 0x00000001
5260: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
5270: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
5280: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
5290: 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 EN_READWRITE
52a0: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 20 20 0x00000002
52b0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
52c0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
52d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
52e0: 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 EN_CREATE
52f0: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 20 20 0x00000004
5300: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
5310: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
5320: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
5330: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 EN_DELETEONCLOSE
5340: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 20 20 0x00000008
5350: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
5360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
5370: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 EN_EXCLUSIVE
5380: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 20 20 0x00000010
5390: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
53a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
53b0: 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 EN_AUTOPROXY
53c0: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 20 20 0x00000020
53d0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
53e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
53f0: 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 EN_MAIN_DB
5400: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 20 20 0x00000100
5410: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
5420: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
5430: 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 EN_TEMP_DB
5440: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 20 20 0x00000200
5450: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
5460: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
5470: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 EN_TRANSIENT_DB
5480: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 20 20 0x00000400
5490: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
54a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
54b0: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 EN_MAIN_JOURNAL
54c0: 20 20 20 20 30 78 30 30 30 30 30 38 30 30 20 20 0x00000800
54d0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
54e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
54f0: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 EN_TEMP_JOURNAL
5500: 20 20 20 20 30 78 30 30 30 30 31 30 30 30 20 20 0x00001000
5510: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
5520: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
5530: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 EN_SUBJOURNAL
5540: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 20 20 0x00002000
5550: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
5560: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
5570: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 EN_MASTER_JOURNA
5580: 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 20 20 L 0x00004000
5590: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
55a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
55b0: 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 EN_NOMUTEX
55c0: 20 20 20 20 30 78 30 30 30 30 38 30 30 30 20 20 0x00008000
55d0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
55e0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
55f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
5600: 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 EN_FULLMUTEX
5610: 20 20 20 20 30 78 30 30 30 31 30 30 30 30 20 20 0x00010000
5620: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
5630: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
5640: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
5650: 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 EN_SHAREDCACHE
5660: 20 20 20 20 30 78 30 30 30 32 30 30 30 30 20 20 0x00020000
5670: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
5680: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
5690: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
56a0: 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 EN_PRIVATECACHE
56b0: 20 20 20 20 30 78 30 30 30 34 30 30 30 30 20 20 0x00040000
56c0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
56d0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
56e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
56f0: 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 EN_WAL
5700: 20 20 20 20 30 78 30 30 30 38 30 30 30 30 20 20 0x00080000
5710: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a /* VFS only */..
5720: 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 /* Reserved:
5730: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
5740: 20 20 20 20 20 30 78 30 30 46 30 30 30 30 30 20 0x00F00000
5750: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
5760: 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 EF: Device Chara
5770: 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a cteristics.**.**
5780: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 The xDeviceChar
5790: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 acteristics meth
57a0: 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 od of the [sqlit
57b0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a e3_io_methods].*
57c0: 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 * object returns
57d0: 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 an integer whic
57e0: 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 h is a vector of
57f0: 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62 69 the these.** bi
5800: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 t values express
5810: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 ing I/O characte
5820: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d ristics of the m
5830: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 ass storage.** d
5840: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 evice that holds
5850: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 the file that t
5860: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d he [sqlite3_io_m
5870: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 ethods].** refer
5880: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 s to..**.** The
5890: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
58a0: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 MIC property mea
58b0: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 ns that all writ
58c0: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a es of.** any siz
58d0: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 e are atomic. T
58e0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
58f0: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 ATOMICnnn values
5900: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 .** mean that wr
5910: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 ites of blocks t
5920: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 hat are nnn byte
5930: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a s in size and.**
5940: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 are aligned to
5950: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 an address which
5960: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d is an integer m
5970: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e ultiple of.** nn
5980: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 n are atomic. T
5990: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
59a0: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 SAFE_APPEND valu
59b0: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 e means.** that
59c0: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 when data is app
59d0: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c ended to a file,
59e0: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 the data is app
59f0: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 ended.** first t
5a00: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 hen the size of
5a10: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 the file is exte
5a20: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 nded, never the
5a30: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f other.** way aro
5a40: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 und. The SQLITE
5a50: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 _IOCAP_SEQUENTIA
5a60: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 L property means
5a70: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 that.** informa
5a80: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 tion is written
5a90: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 to disk in the s
5aa0: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c ame order as cal
5ab0: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 ls.** to xWrite(
5ac0: 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 )..*/.#define SQ
5ad0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
5ae0: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 C
5af0: 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 0x00000001.#de
5b00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
5b10: 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 P_ATOMIC512
5b20: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
5b30: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 002.#define SQLI
5b40: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 TE_IOCAP_ATOMIC1
5b50: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 K
5b60: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 0x00000004.#defi
5b70: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
5b80: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 ATOMIC2K
5b90: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 0x0000000
5ba0: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 8.#define SQLITE
5bb0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 _IOCAP_ATOMIC4K
5bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 0x
5bd0: 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 00000010.#define
5be0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
5bf0: 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 OMIC8K
5c00: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 0x00000020.
5c10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5c20: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 OCAP_ATOMIC16K
5c30: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
5c40: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 000040.#define S
5c50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
5c60: 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 IC32K
5c70: 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 0x00000080.#d
5c80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
5c90: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 AP_ATOMIC64K
5ca0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
5cb0: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0100.#define SQL
5cc0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 ITE_IOCAP_SAFE_A
5cd0: 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 PPEND
5ce0: 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 0x00000200.#def
5cf0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
5d00: 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 _SEQUENTIAL
5d10: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 34 0x000004
5d20: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 00.#define SQLIT
5d30: 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 E_IOCAP_UNDELETA
5d40: 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 BLE_WHEN_OPEN 0
5d50: 78 30 30 30 30 30 38 30 30 0a 0a 2f 2a 0a 2a 2a x00000800../*.**
5d60: 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 CAPI3REF: File
5d70: 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a Locking Levels.*
5d80: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 *.** SQLite uses
5d90: 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e one of these in
5da0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 teger values as
5db0: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 the second.** ar
5dc0: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 gument to calls
5dd0: 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 it makes to the
5de0: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c xLock() and xUnl
5df0: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a ock() methods.**
5e00: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f of an [sqlite3_
5e10: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 io_methods] obje
5e20: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ct..*/.#define S
5e30: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 QLITE_LOCK_NONE
5e40: 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 0.#defi
5e50: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 ne SQLITE_LOCK_S
5e60: 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 HARED 1.#
5e70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f define SQLITE_LO
5e80: 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 CK_RESERVED
5e90: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 2.#define SQLIT
5ea0: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 E_LOCK_PENDING
5eb0: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 3.#define S
5ec0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 QLITE_LOCK_EXCLU
5ed0: 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a SIVE 4../*.*
5ee0: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 * CAPI3REF: Sync
5ef0: 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 hronization Type
5f00: 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 Flags.**.** Whe
5f10: 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 n SQLite invokes
5f20: 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 the xSync() met
5f30: 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 hod of an.** [sq
5f40: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
5f50: 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 ] object it uses
5f60: 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f a combination o
5f70: 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 f.** these integ
5f80: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 er values as the
5f90: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
5fa0: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 ..**.** When the
5fb0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 SQLITE_SYNC_DAT
5fc0: 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 AONLY flag is us
5fd0: 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 ed, it means tha
5fe0: 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 t the.** sync op
5ff0: 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 eration only nee
6000: 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 ds to flush data
6010: 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 to mass storage
6020: 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f . Inode.** info
6030: 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 rmation need not
6040: 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 be flushed. If
6050: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 the lower four b
6060: 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a its of the flag.
6070: 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f ** equal SQLITE_
6080: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 SYNC_NORMAL, tha
6090: 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e t means to use n
60a0: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 ormal fsync() se
60b0: 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 mantics..** If t
60c0: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 he lower four bi
60d0: 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f ts equal SQLITE_
60e0: 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 SYNC_FULL, that
60f0: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 means.** to use
6100: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 Mac OS X style f
6110: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 ullsync instead
6120: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a of fsync()..**.*
6130: 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 * Do not confuse
6140: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 the SQLITE_SYNC
6150: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 _NORMAL and SQLI
6160: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 TE_SYNC_FULL fla
6170: 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b gs.** with the [
6180: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f PRAGMA synchrono
6190: 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b us]=NORMAL and [
61a0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f PRAGMA synchrono
61b0: 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 us]=FULL.** sett
61c0: 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 ings. The [sync
61d0: 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 hronous pragma]
61e0: 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 determines when
61f0: 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 calls to the.**
6200: 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 xSync VFS method
6210: 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 occur and appli
6220: 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 es uniformly acr
6230: 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d oss all platform
6240: 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 s..** The SQLITE
6250: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 _SYNC_NORMAL and
6260: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c SQLITE_SYNC_FUL
6270: 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e L flags determin
6280: 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 e how.** energet
6290: 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f ic or rigorous o
62a0: 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 r forceful the s
62b0: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 ync operations a
62c0: 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d re and.** only m
62d0: 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 ake a difference
62e0: 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 on Mac OSX for
62f0: 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 the default SQLi
6300: 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 te code..** (Thi
6310: 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 rd-party VFS imp
6320: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 lementations mig
6330: 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 ht also make the
6340: 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 distinction.**
6350: 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 between SQLITE_S
6360: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 YNC_NORMAL and S
6370: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c QLITE_SYNC_FULL,
6380: 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a but among the.*
6390: 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 * operating syst
63a0: 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 ems natively sup
63b0: 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 ported by SQLite
63c0: 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a , only Mac OSX.*
63d0: 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 * cares about th
63e0: 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a e difference.).*
63f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6400: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 _SYNC_NORMAL
6410: 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 0x00002.#def
6420: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f ine SQLITE_SYNC_
6430: 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 FULL 0x
6440: 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 00003.#define SQ
6450: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e LITE_SYNC_DATAON
6460: 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a LY 0x00010.
6470: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
6480: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 OS Interface Op
6490: 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a en File Handle.*
64a0: 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 *.** An [sqlite3
64b0: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 _file] object re
64c0: 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e presents an open
64d0: 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a file in the .**
64e0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 [sqlite3_vfs |
64f0: 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 OS interface lay
6500: 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c er]. Individual
6510: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a OS interface.**
6520: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
6530: 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f will.** want to
6540: 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f subclass this o
6550: 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 bject by appendi
6560: 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 ng additional fi
6570: 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 elds.** for thei
6580: 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 r own use. The
6590: 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 pMethods entry i
65a0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
65b0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f n.** [sqlite3_io
65c0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 _methods] object
65d0: 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 that defines me
65e0: 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 thods for perfor
65f0: 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 ming.** I/O oper
6600: 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 ations on the op
6610: 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 en file..*/.type
6620: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
6630: 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f e3_file sqlite3_
6640: 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c file;.struct sql
6650: 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f ite3_file {. co
6660: 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 nst struct sqlit
6670: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 e3_io_methods *p
6680: 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 Methods; /* Met
6690: 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e hods for an open
66a0: 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a file */.};../*.
66b0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 ** CAPI3REF: OS
66c0: 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 Interface File V
66d0: 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f irtual Methods O
66e0: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 bject.**.** Ever
66f0: 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 y file opened by
6700: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 the [sqlite3_vf
6710: 73 5d 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 s] xOpen method
6720: 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 populates an.**
6730: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f [sqlite3_file] o
6740: 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 bject (or, more
6750: 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 commonly, a subc
6760: 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b lass of the.** [
6770: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 sqlite3_file] ob
6780: 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 ject) with a poi
6790: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 nter to an insta
67a0: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 nce of this obje
67b0: 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 ct..** This obje
67c0: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d ct defines the m
67d0: 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 ethods used to p
67e0: 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f erform various o
67f0: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 perations.** aga
6800: 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 inst the open fi
6810: 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 le represented b
6820: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 y the [sqlite3_f
6830: 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a ile] object..**.
6840: 2a 2a 20 49 66 20 74 68 65 20 78 4f 70 65 6e 20 ** If the xOpen
6850: 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 method sets the
6860: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 sqlite3_file.pMe
6870: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a thods element .*
6880: 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 * to a non-NULL
6890: 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 pointer, then th
68a0: 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 e sqlite3_io_met
68b0: 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 hods.xClose meth
68c0: 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 od.** may be inv
68d0: 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 oked even if the
68e0: 20 78 4f 70 65 6e 20 72 65 70 6f 72 74 65 64 20 xOpen reported
68f0: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 that it failed.
6900: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 The.** only way
6910: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 to prevent a ca
6920: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c ll to xClose fol
6930: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 lowing a failed
6940: 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 66 6f 72 20 xOpen.** is for
6950: 74 68 65 20 78 4f 70 65 6e 20 74 6f 20 73 65 74 the xOpen to set
6960: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c the sqlite3_fil
6970: 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 e.pMethods eleme
6980: 6e 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a nt to NULL..**.*
6990: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 * The flags argu
69a0: 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 ment to xSync ma
69b0: 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c y be one of [SQL
69c0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d ITE_SYNC_NORMAL]
69d0: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 or.** [SQLITE_S
69e0: 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 YNC_FULL]. The
69f0: 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 first choice is
6a00: 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 the normal fsync
6a10: 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e ()..** The secon
6a20: 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 d choice is a Ma
6a30: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c c OS X style ful
6a40: 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c lsync. The [SQL
6a50: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c ITE_SYNC_DATAONL
6a60: 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 Y].** flag may b
6a70: 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 e ORed in to ind
6a80: 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 icate that only
6a90: 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 the data of the
6aa0: 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 file.** and not
6ab0: 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 its inode needs
6ac0: 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a to be synced..**
6ad0: 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 .** The integer
6ae0: 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 values to xLock(
6af0: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 ) and xUnlock()
6b00: 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 are one of.** <u
6b10: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 l>.** <li> [SQLI
6b20: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a TE_LOCK_NONE],.*
6b30: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c * <li> [SQLITE_L
6b40: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 OCK_SHARED],.**
6b50: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 <li> [SQLITE_LOC
6b60: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 K_RESERVED],.**
6b70: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 <li> [SQLITE_LOC
6b80: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a K_PENDING], or.*
6b90: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c * <li> [SQLITE_L
6ba0: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a OCK_EXCLUSIVE]..
6bb0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 ** </ul>.** xLoc
6bc0: 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 k() increases th
6bd0: 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 e lock. xUnlock(
6be0: 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 ) decreases the
6bf0: 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 lock..** The xCh
6c00: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 eckReservedLock(
6c10: 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 ) method checks
6c20: 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 whether any data
6c30: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c base connection,
6c40: 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 .** either in th
6c50: 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e is process or in
6c60: 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 some other proc
6c70: 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 ess, is holding
6c80: 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 a RESERVED,.** P
6c90: 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 ENDING, or EXCLU
6ca0: 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 SIVE lock on the
6cb0: 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 file. It retur
6cc0: 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 ns true.** if su
6cd0: 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 ch a lock exists
6ce0: 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 and false other
6cf0: 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 wise..**.** The
6d00: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d xFileControl() m
6d10: 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 ethod is a gener
6d20: 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 ic interface tha
6d30: 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a t allows custom.
6d40: 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 ** VFS implement
6d50: 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 ations to direct
6d60: 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 ly control an op
6d70: 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 en file using th
6d80: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 e.** [sqlite3_fi
6d90: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e le_control()] in
6da0: 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 terface. The se
6db0: 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 cond "op" argume
6dc0: 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 nt is an.** inte
6dd0: 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 ger opcode. The
6de0: 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 third argument
6df0: 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 is a generic poi
6e00: 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f nter intended to
6e10: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 .** point to a s
6e20: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 tructure that ma
6e30: 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 y contain argume
6e40: 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 nts or space in
6e50: 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 which to.** writ
6e60: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e e return values.
6e70: 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 Potential uses
6e80: 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f for xFileContro
6e90: 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 l() might be.**
6ea0: 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 functions to ena
6eb0: 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 ble blocking loc
6ec0: 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 ks with timeouts
6ed0: 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a , to change the.
6ee0: 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 ** locking strat
6ef0: 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 egy (for example
6f00: 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 to use dot-file
6f10: 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 locks), to inqu
6f20: 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 ire.** about the
6f30: 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 status of a loc
6f40: 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 k, or to break s
6f50: 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 tale locks. The
6f60: 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 SQLite.** core
6f70: 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 reserves all opc
6f80: 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 odes less than 1
6f90: 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 00 for its own u
6fa0: 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 se..** A [SQLITE
6fb0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 _FCNTL_LOCKSTATE
6fc0: 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 | list of opcod
6fd0: 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 es] less than 10
6fe0: 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 0 is available..
6ff0: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 ** Applications
7000: 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 that define a cu
7010: 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f stom xFileContro
7020: 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 l method should
7030: 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 use opcodes.** g
7040: 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 reater than 100
7050: 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 to avoid conflic
7060: 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 ts. VFS impleme
7070: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a ntations should.
7080: 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 ** return [SQLIT
7090: 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 E_NOTFOUND] for
70a0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 file control opc
70b0: 6f 64 65 73 20 74 68 61 74 20 74 68 65 79 20 64 odes that they d
70c0: 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 o not.** recogni
70d0: 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 ze..**.** The xS
70e0: 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 ectorSize() meth
70f0: 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 od returns the s
7100: 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 ector size of th
7110: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 e.** device that
7120: 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 underlies the f
7130: 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 ile. The sector
7140: 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 size is the.**
7150: 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 minimum write th
7160: 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 at can be perfor
7170: 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 med without dist
7180: 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 urbing.** other
7190: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c bytes in the fil
71a0: 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 43 e. The xDeviceC
71b0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28 29 haracteristics()
71c0: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 .** method retur
71d0: 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 ns a bit vector
71e0: 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 describing behav
71f0: 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 iors of the.** u
7200: 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 nderlying device
7210: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
7220: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
7230: 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c AP_ATOMIC].** <l
7240: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
7250: 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c _ATOMIC512].** <
7260: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
7270: 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c P_ATOMIC1K].** <
7280: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
7290: 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c P_ATOMIC2K].** <
72a0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
72b0: 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c P_ATOMIC4K].** <
72c0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
72d0: 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c P_ATOMIC8K].** <
72e0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
72f0: 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 P_ATOMIC16K].**
7300: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
7310: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a AP_ATOMIC32K].**
7320: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
7330: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a CAP_ATOMIC64K].*
7340: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
7350: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 OCAP_SAFE_APPEND
7360: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
7370: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 E_IOCAP_SEQUENTI
7380: 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a AL].** </ul>.**.
7390: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f ** The SQLITE_IO
73a0: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 CAP_ATOMIC prope
73b0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 rty means that a
73c0: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 ll writes of.**
73d0: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f any size are ato
73e0: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 mic. The SQLITE
73f0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e _IOCAP_ATOMICnnn
7400: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 values.** mean
7410: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 that writes of b
7420: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e locks that are n
7430: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 nn bytes in size
7440: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 and.** are alig
7450: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 ned to an addres
7460: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e s which is an in
7470: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f teger multiple o
7480: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f f.** nnn are ato
7490: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 mic. The SQLITE
74a0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 _IOCAP_SAFE_APPE
74b0: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a ND value means.*
74c0: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 * that when data
74d0: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 is appended to
74e0: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 a file, the data
74f0: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 is appended.**
7500: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 first then the s
7510: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 ize of the file
7520: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 is extended, nev
7530: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 er the other.**
7540: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 way around. The
7550: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 SQLITE_IOCAP_SE
7560: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 QUENTIAL propert
7570: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 y means that.**
7580: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 information is w
7590: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 ritten to disk i
75a0: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 n the same order
75b0: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 as calls.** to
75c0: 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 xWrite()..**.**
75d0: 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75 72 If xRead() retur
75e0: 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ns SQLITE_IOERR_
75f0: 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 SHORT_READ it mu
7600: 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 st also fill.**
7610: 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f in the unread po
7620: 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 rtions of the bu
7630: 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e ffer with zeros.
7640: 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 A VFS that.**
7650: 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 fails to zero-fi
7660: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d ll short reads m
7670: 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 ight seem to wor
7680: 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 k. However,.**
7690: 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d failure to zero-
76a0: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 fill short reads
76b0: 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 will eventually
76c0: 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 lead to.** data
76d0: 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e base corruption.
76e0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
76f0: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 ct sqlite3_io_me
7700: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f thods sqlite3_io
7710: 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 _methods;.struct
7720: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 sqlite3_io_meth
7730: 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 ods {. int iVer
7740: 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 sion;. int (*xC
7750: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 lose)(sqlite3_fi
7760: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 le*);. int (*xR
7770: 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ead)(sqlite3_fil
7780: 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 e*, void*, int i
7790: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 Amt, sqlite3_int
77a0: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 64 iOfst);. int
77b0: 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 (*xWrite)(sqlit
77c0: 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 e3_file*, const
77d0: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c void*, int iAmt,
77e0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 sqlite3_int64 i
77f0: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 Ofst);. int (*x
7800: 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 Truncate)(sqlite
7810: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 3_file*, sqlite3
7820: 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 _int64 size);.
7830: 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c int (*xSync)(sql
7840: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 ite3_file*, int
7850: 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a flags);. int (*
7860: 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 xFileSize)(sqlit
7870: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 e3_file*, sqlite
7880: 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 3_int64 *pSize);
7890: 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 . int (*xLock)(
78a0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
78b0: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e nt);. int (*xUn
78c0: 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 lock)(sqlite3_fi
78d0: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 le*, int);. int
78e0: 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 (*xCheckReserve
78f0: 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 dLock)(sqlite3_f
7900: 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f ile*, int *pResO
7910: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 ut);. int (*xFi
7920: 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 leControl)(sqlit
7930: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 e3_file*, int op
7940: 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 , void *pArg);.
7950: 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 int (*xSectorSi
7960: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ze)(sqlite3_file
7970: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 *);. int (*xDev
7980: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 iceCharacteristi
7990: 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 cs)(sqlite3_file
79a0: 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 *);. /* Methods
79b0: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 above are valid
79c0: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a for version 1 *
79d0: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 /. int (*xShmMa
79e0: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a p)(sqlite3_file*
79f0: 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 , int iPg, int p
7a00: 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 gsz, int, void v
7a10: 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e olatile**);. in
7a20: 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 t (*xShmLock)(sq
7a30: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 lite3_file*, int
7a40: 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 offset, int n,
7a50: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f int flags);. vo
7a60: 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 id (*xShmBarrier
7a70: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 )(sqlite3_file*)
7a80: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e ;. int (*xShmUn
7a90: 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c map)(sqlite3_fil
7aa0: 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c e*, int deleteFl
7ab0: 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 ag);. /* Method
7ac0: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 s above are vali
7ad0: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 d for version 2
7ae0: 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e */. /* Addition
7af0: 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 al methods may b
7b00: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
7b10: 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b e releases */.};
7b20: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
7b30: 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 : Standard File
7b40: 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a Control Opcodes.
7b50: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 **.** These inte
7b60: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 ger constants ar
7b70: 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 e opcodes for th
7b80: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d e xFileControl m
7b90: 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 ethod.** of the
7ba0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
7bb0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 ods] object and
7bc0: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 for the [sqlite3
7bd0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d _file_control()]
7be0: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a .** interface..*
7bf0: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 *.** The [SQLITE
7c00: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 _FCNTL_LOCKSTATE
7c10: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 ] opcode is used
7c20: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 for debugging.
7c30: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 This.** opcode
7c40: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 causes the xFile
7c50: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 Control method t
7c60: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 o write the curr
7c70: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 ent state of.**
7c80: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 the lock (one of
7c90: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f [SQLITE_LOCK_NO
7ca0: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 NE], [SQLITE_LOC
7cb0: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 K_SHARED],.** [S
7cc0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 QLITE_LOCK_RESER
7cd0: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f VED], [SQLITE_LO
7ce0: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 CK_PENDING], or
7cf0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 [SQLITE_LOCK_EXC
7d00: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f LUSIVE]).** into
7d10: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 an integer that
7d20: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 the pArg argume
7d30: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 nt points to. Th
7d40: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a is capability.**
7d50: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 is used during
7d60: 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 testing and only
7d70: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 needs to be sup
7d80: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 ported when SQLI
7d90: 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 TE_TEST.** is de
7da0: 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 fined..**.** The
7db0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 [SQLITE_FCNTL_S
7dc0: 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 IZE_HINT] opcode
7dd0: 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 is used by SQLi
7de0: 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 te to give the V
7df0: 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 FS.** layer a hi
7e00: 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 nt of how large
7e10: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
7e20: 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 e will grow to b
7e30: 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 e during the.**
7e40: 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 current transact
7e50: 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 ion. This hint
7e60: 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 is not guarantee
7e70: 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 d to be accurate
7e80: 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 but it.** is of
7e90: 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 ten close. The
7ea0: 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d underlying VFS m
7eb0: 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 ight choose to p
7ec0: 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 reallocate datab
7ed0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 ase.** file spac
7ee0: 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 e based on this
7ef0: 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f hint in order to
7f00: 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 help writes to
7f10: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 the database.**
7f20: 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e file run faster.
7f30: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 .**.** The [SQLI
7f40: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 TE_FCNTL_CHUNK_S
7f50: 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 IZE] opcode is u
7f60: 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 sed to request t
7f70: 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 hat the VFS.** e
7f80: 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 xtends and trunc
7f90: 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73 ates the databas
7fa0: 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 e file in chunks
7fb0: 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 of a size speci
7fc0: 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 fied.** by the u
7fd0: 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 ser. The fourth
7fe0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c argument to [sql
7ff0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
8000: 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 l()] should .**
8010: 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 point to an inte
8020: 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 ger (type int) c
8030: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 ontaining the ne
8040: 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 w chunk-size to
8050: 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e use.** for the n
8060: 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 ominated databas
8070: 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 e. Allocating da
8080: 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 tabase file spac
8090: 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 e in large.** ch
80a0: 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 unks (say 1MB at
80b0: 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 a time), may re
80c0: 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d duce file-system
80d0: 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 fragmentation a
80e0: 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 nd.** improve pe
80f0: 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d rformance on som
8100: 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a e systems..**.**
8110: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e The [SQLITE_FCN
8120: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d TL_FILE_POINTER]
8130: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 opcode is used
8140: 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e to obtain a poin
8150: 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 ter.** to the [s
8160: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a qlite3_file] obj
8170: 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 ect associated w
8180: 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 ith a particular
8190: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e database.** con
81a0: 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 nection. See th
81b0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f e [sqlite3_file_
81c0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d control()] docum
81d0: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 entation for.**
81e0: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 additional infor
81f0: 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 28 mation..**.** ^(
8200: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
8210: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 L_SYNC_OMITTED]
8220: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 opcode is genera
8230: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 ted internally b
8240: 79 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 y.** SQLite and
8250: 73 65 6e 74 20 74 6f 20 61 6c 6c 20 56 46 53 65 sent to all VFSe
8260: 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 61 20 s in place of a
8270: 63 61 6c 6c 20 74 6f 20 74 68 65 20 78 53 79 6e call to the xSyn
8280: 63 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e c method.** when
8290: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
82a0: 6e 6e 65 63 74 69 6f 6e 20 68 61 73 20 5b 50 52 nnection has [PR
82b0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 AGMA synchronous
82c0: 5d 20 73 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a ] set to OFF.)^.
82d0: 2a 2a 20 53 6f 6d 65 20 73 70 65 63 69 61 6c 69 ** Some speciali
82e0: 7a 65 64 20 56 46 53 65 73 20 6e 65 65 64 20 74 zed VFSes need t
82f0: 68 69 73 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72 his signal in or
8300: 64 65 72 20 74 6f 20 6f 70 65 72 61 74 65 20 63 der to operate c
8310: 6f 72 72 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e orrectly.** when
8320: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f [PRAGMA synchro
8330: 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 nous | PRAGMA sy
8340: 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 nchronous=OFF] i
8350: 73 20 73 65 74 2c 20 62 75 74 20 6d 6f 73 74 20 s set, but most
8360: 0a 2a 2a 20 56 46 53 65 73 20 64 6f 20 6e 6f 74 .** VFSes do not
8370: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 need this signa
8380: 6c 20 61 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c l and should sil
8390: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 ently ignore thi
83a0: 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 s opcode..** App
83b0: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 lications should
83c0: 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 not call [sqlit
83d0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
83e0: 29 5d 20 77 69 74 68 20 74 68 69 73 0a 2a 2a 20 )] with this.**
83f0: 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 opcode as doing
8400: 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 so may disrupt t
8410: 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 he operation of
8420: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 the specialized
8430: 56 46 53 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f VFSes.** that do
8440: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a require it. .*
8450: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
8460: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 _FCNTL_LOCKSTATE
8470: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 1.#defin
8480: 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 e SQLITE_GET_LOC
8490: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 KPROXYFILE
84a0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
84b0: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 _SET_LOCKPROXYFI
84c0: 4c 45 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e LE 3.#defin
84d0: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 e SQLITE_LAST_ER
84e0: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 RNO
84f0: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
8500: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 _FCNTL_SIZE_HINT
8510: 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 5.#defin
8520: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 e SQLITE_FCNTL_C
8530: 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 HUNK_SIZE
8540: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 6.#define SQLITE
8550: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e _FCNTL_FILE_POIN
8560: 54 45 52 20 20 20 20 20 37 0a 23 64 65 66 69 6e TER 7.#defin
8570: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 e SQLITE_FCNTL_S
8580: 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 YNC_OMITTED
8590: 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 8.../*.** CAPI3R
85a0: 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 EF: Mutex Handle
85b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 .**.** The mutex
85c0: 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 module within S
85d0: 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 QLite defines [s
85e0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f qlite3_mutex] to
85f0: 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 be an.** abstra
8600: 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 ct type for a mu
8610: 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 tex object. The
8620: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 SQLite core nev
8630: 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 er looks.** at t
8640: 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 he internal repr
8650: 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e esentation of an
8660: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d [sqlite3_mutex]
8670: 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 . It only.** de
8680: 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 als with pointer
8690: 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 s to the [sqlite
86a0: 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 3_mutex] object.
86b0: 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 .**.** Mutexes a
86c0: 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 re created using
86d0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
86e0: 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 alloc()]..*/.typ
86f0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
8700: 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 te3_mutex sqlite
8710: 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 3_mutex;../*.**
8720: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 CAPI3REF: OS Int
8730: 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a erface Object.**
8740: 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 .** An instance
8750: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 of the sqlite3_v
8760: 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 fs object define
8770: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 s the interface
8780: 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 between.** the S
8790: 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 QLite core and t
87a0: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 he underlying op
87b0: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 erating system.
87c0: 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e The "vfs".** in
87d0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
87e0: 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 object stands f
87f0: 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 or "virtual file
8800: 20 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 system"..**.**
8810: 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 The value of the
8820: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 iVersion field
8830: 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 is initially 1 b
8840: 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 ut may be larger
8850: 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 in.** future ve
8860: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
8870: 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 . Additional fi
8880: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 elds may be appe
8890: 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 nded to this.**
88a0: 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 object when the
88b0: 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 iVersion value i
88c0: 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f s increased. No
88d0: 74 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75 te that the stru
88e0: 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 cture.** of the
88f0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 sqlite3_vfs obje
8900: 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 ct changes in th
8910: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 e transaction be
8920: 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 tween.** SQLite
8930: 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e version 3.5.9 an
8940: 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 d 3.6.0 and yet
8950: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 the iVersion fie
8960: 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f ld was not.** mo
8970: 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 dified..**.** Th
8980: 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 e szOsFile field
8990: 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 is the size of
89a0: 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b the subclassed [
89b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a sqlite3_file].**
89c0: 20 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20 structure used
89d0: 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 by this VFS. mx
89e0: 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 Pathname is the
89f0: 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f maximum length o
8a00: 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 f.** a pathname
8a10: 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a in this VFS..**.
8a20: 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71 ** Registered sq
8a30: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 lite3_vfs object
8a40: 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 s are kept on a
8a50: 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d linked list form
8a60: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 ed by.** the pNe
8a70: 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 xt pointer. The
8a80: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 [sqlite3_vfs_re
8a90: 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 gister()].** and
8aa0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e [sqlite3_vfs_un
8ab0: 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 register()] inte
8ac0: 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 rfaces manage th
8ad0: 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 is list.** in a
8ae0: 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e thread-safe way.
8af0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 The [sqlite3_v
8b00: 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 fs_find()] inter
8b10: 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 face.** searches
8b20: 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 the list. Neit
8b30: 68 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 her the applicat
8b40: 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 ion code nor the
8b50: 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e VFS.** implemen
8b60: 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 tation should us
8b70: 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e e the pNext poin
8b80: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 ter..**.** The p
8b90: 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 Next field is th
8ba0: 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 e only field in
8bb0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a the sqlite3_vfs.
8bc0: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61 ** structure tha
8bd0: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 t SQLite will ev
8be0: 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 er modify. SQLi
8bf0: 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 te will only acc
8c00: 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 ess.** or modify
8c10: 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c this field whil
8c20: 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 e holding a part
8c30: 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 icular static mu
8c40: 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c tex..** The appl
8c50: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e ication should n
8c60: 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 ever modify anyt
8c70: 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 hing within the
8c80: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f sqlite3_vfs.** o
8c90: 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f bject once the o
8ca0: 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 bject has been r
8cb0: 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a egistered..**.**
8cc0: 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 The zName field
8cd0: 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 holds the name
8ce0: 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c of the VFS modul
8cf0: 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 e. The name mus
8d00: 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 t.** be unique a
8d10: 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f cross all VFS mo
8d20: 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 dules..**.** ^SQ
8d30: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 Lite guarantees
8d40: 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 that the zFilena
8d50: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 me parameter to
8d60: 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 xOpen.** is eith
8d70: 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 er a NULL pointe
8d80: 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 r or string obta
8d90: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 ined.** from xFu
8da0: 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 llPathname() wit
8db0: 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 h an optional su
8dc0: 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e ffix added..** ^
8dd0: 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61 If a suffix is a
8de0: 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c dded to the zFil
8df0: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c ename parameter,
8e00: 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 it will.** cons
8e10: 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 ist of a single
8e20: 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f "-" character fo
8e30: 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 llowed by no mor
8e40: 65 20 74 68 61 6e 0a 2a 2a 20 31 30 20 61 6c 70 e than.** 10 alp
8e50: 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 hanumeric and/or
8e60: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e "-" characters.
8e70: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 .** ^SQLite furt
8e80: 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 her guarantees t
8e90: 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e hat.** the strin
8ea0: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 g will be valid
8eb0: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e and unchanged un
8ec0: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a til xClose() is.
8ed0: 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 ** called. Becau
8ee0: 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f se of the previo
8ef0: 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 us sentence,.**
8f00: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c the [sqlite3_fil
8f10: 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 e] can safely st
8f20: 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f ore a pointer to
8f30: 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 the.** filename
8f40: 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 if it needs to
8f50: 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c remember the fil
8f60: 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 ename for some r
8f70: 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 eason..** If the
8f80: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d zFilename param
8f90: 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 eter to xOpen is
8fa0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
8fb0: 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 then xOpen.** mu
8fc0: 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 st invent its ow
8fd0: 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 n temporary name
8fe0: 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 for the file.
8ff0: 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a ^Whenever the .*
9000: 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 * xFilename para
9010: 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 meter is NULL it
9020: 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 will also be th
9030: 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a e case that the.
9040: 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 ** flags paramet
9050: 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 er will include
9060: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c [SQLITE_OPEN_DEL
9070: 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a ETEONCLOSE]..**.
9080: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 ** The flags arg
9090: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 ument to xOpen()
90a0: 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 includes all bi
90b0: 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 ts set in.** the
90c0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 flags argument
90d0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e to [sqlite3_open
90e0: 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b _v2()]. Or if [
90f0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a sqlite3_open()].
9100: 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f ** or [sqlite3_o
9110: 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 pen16()] is used
9120: 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 , then flags inc
9130: 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a ludes at least.*
9140: 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 * [SQLITE_OPEN_R
9150: 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c EADWRITE] | [SQL
9160: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d ITE_OPEN_CREATE]
9170: 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 . .** If xOpen()
9180: 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 opens a file re
9190: 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 ad-only then it
91a0: 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 sets *pOutFlags
91b0: 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 to.** include [S
91c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f QLITE_OPEN_READO
91d0: 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 NLY]. Other bit
91e0: 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 s in *pOutFlags
91f0: 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a may be set..**.*
9200: 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 * ^(SQLite will
9210: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 also add one of
9220: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c the following fl
9230: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e ags to the xOpen
9240: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 ().** call, depe
9250: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a nding on the obj
9260: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 ect being opened
9270: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
9280: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
9290: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c EN_MAIN_DB].** <
92a0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
92b0: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a N_MAIN_JOURNAL].
92c0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
92d0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a _OPEN_TEMP_DB].*
92e0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
92f0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 OPEN_TEMP_JOURNA
9300: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c L].** <li> [SQL
9310: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 ITE_OPEN_TRANSIE
9320: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 NT_DB].** <li>
9330: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 [SQLITE_OPEN_SUB
9340: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e JOURNAL].** <li>
9350: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d [SQLITE_OPEN_M
9360: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a ASTER_JOURNAL].*
9370: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
9380: 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 OPEN_WAL].** </u
9390: 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 l>)^.**.** The f
93a0: 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e ile I/O implemen
93b0: 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 tation can use t
93c0: 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 he object type f
93d0: 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 lags to.** chang
93e0: 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61 e the way it dea
93f0: 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 ls with files.
9400: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 For example, an
9410: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 application.** t
9420: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 hat does not car
9430: 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 e about crash re
9440: 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 covery or rollba
9450: 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a ck might make.**
9460: 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a the open of a j
9470: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f ournal file a no
9480: 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 -op. Writes to
9490: 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 this journal wou
94a0: 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f ld.** also be no
94b0: 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 -ops, and any at
94c0: 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 tempt to read th
94d0: 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 e journal would
94e0: 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 return.** SQLITE
94f0: 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 _IOERR. Or the
9500: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d implementation m
9510: 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 ight recognize t
9520: 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a hat a database.*
9530: 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 * file will be d
9540: 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 oing page-aligne
9550: 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 d sector reads a
9560: 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 nd writes in a r
9570: 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 andom.** order a
9580: 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f nd set up its I/
9590: 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f O subsystem acco
95a0: 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 rdingly..**.** S
95b0: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f QLite might also
95c0: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 add one of the
95d0: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 following flags
95e0: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 to the xOpen met
95f0: 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a hod:.**.** <ul>.
9600: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
9610: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f OPEN_DELETEONCLO
9620: 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c SE].** <li> [SQL
9630: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 ITE_OPEN_EXCLUSI
9640: 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a VE].** </ul>.**.
9650: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f ** The [SQLITE_O
9660: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 PEN_DELETEONCLOS
9670: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 E] flag means th
9680: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 e file should be
9690: 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e .** deleted when
96a0: 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 it is closed.
96b0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 ^The [SQLITE_OPE
96c0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d N_DELETEONCLOSE]
96d0: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 .** will be set
96e0: 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 for TEMP databas
96f0: 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 es and their jou
9700: 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 rnals, transient
9710: 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 .** databases, a
9720: 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a nd subjournals..
9730: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 **.** ^The [SQLI
9740: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 TE_OPEN_EXCLUSIV
9750: 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 E] flag is alway
9760: 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e s used in conjun
9770: 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 ction.** with th
9780: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 e [SQLITE_OPEN_C
9790: 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 REATE] flag, whi
97a0: 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 ch are both dire
97b0: 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 ctly.** analogou
97c0: 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 s to the O_EXCL
97d0: 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 and O_CREAT flag
97e0: 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f s of the POSIX o
97f0: 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 pen().** API. T
9800: 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 he SQLITE_OPEN_E
9810: 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 XCLUSIVE flag, w
9820: 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 hen paired with
9830: 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f the .** SQLITE_O
9840: 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 PEN_CREATE, is u
9850: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 sed to indicate
9860: 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 that file should
9870: 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 always.** be cr
9880: 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 eated, and that
9890: 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 it is an error i
98a0: 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 f it already exi
98b0: 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 sts..** It is <i
98c0: 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f >not</i> used to
98d0: 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 indicate the fi
98e0: 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 le should be ope
98f0: 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c ned .** for excl
9900: 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a usive access..**
9910: 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a .** ^At least sz
9920: 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 OsFile bytes of
9930: 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 memory are alloc
9940: 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a ated by SQLite.*
9950: 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b * to hold the [
9960: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 sqlite3_file] st
9970: 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61 ructure passed a
9980: 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 s the third.** a
9990: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e rgument to xOpen
99a0: 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 . The xOpen met
99b0: 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 hod does not hav
99c0: 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 e to.** allocate
99d0: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 the structure;
99e0: 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 it should just f
99f0: 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 ill it in. Note
9a00: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 that.** the xOp
9a10: 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 en method must s
9a20: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 et the sqlite3_f
9a30: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 ile.pMethods to
9a40: 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 either.** a vali
9a50: 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 d [sqlite3_io_me
9a60: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 thods] object or
9a70: 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e to NULL. xOpen
9a80: 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 must do.** this
9a90: 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 even if the ope
9aa0: 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 n fails. SQLite
9ab0: 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68 expects that th
9ac0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 e sqlite3_file.p
9ad0: 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 Methods.** eleme
9ae0: 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 nt will be valid
9af0: 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 after xOpen ret
9b00: 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 urns regardless
9b10: 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a of the success.*
9b20: 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 * or failure of
9b30: 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a the xOpen call..
9b40: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 **.** ^The flags
9b50: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 argument to xAc
9b60: 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 cess() may be [S
9b70: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 QLITE_ACCESS_EXI
9b80: 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 STS].** to test
9b90: 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 for the existenc
9ba0: 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 e of a file, or
9bb0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 [SQLITE_ACCESS_R
9bc0: 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 EADWRITE] to.**
9bd0: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 test whether a f
9be0: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 ile is readable
9bf0: 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 and writable, or
9c00: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f [SQLITE_ACCESS_
9c10: 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 READ].** to test
9c20: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 whether a file
9c30: 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 is at least read
9c40: 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 able. The file
9c50: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 can be a.** dir
9c60: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 ectory..**.** ^S
9c70: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 QLite will alway
9c80: 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 s allocate at le
9c90: 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 ast mxPathname+1
9ca0: 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a bytes for the.*
9cb0: 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 * output buffer
9cc0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 xFullPathname.
9cd0: 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f The exact size o
9ce0: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 f the output buf
9cf0: 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 fer.** is also p
9d00: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d assed as a param
9d10: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 eter to both me
9d20: 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 thods. If the ou
9d30: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 tput buffer.** i
9d40: 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 s not large enou
9d50: 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 gh, [SQLITE_CANT
9d60: 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 OPEN] should be
9d70: 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 returned. Since
9d80: 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c this is.** handl
9d90: 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 ed as a fatal er
9da0: 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 ror by SQLite, v
9db0: 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f fs implementatio
9dc0: 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 ns should endeav
9dd0: 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 or.** to prevent
9de0: 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 this by setting
9df0: 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 mxPathname to a
9e00: 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 sufficiently la
9e10: 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a rge value..**.**
9e20: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 The xRandomness
9e30: 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 (), xSleep(), xC
9e40: 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e urrentTime(), an
9e50: 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e d xCurrentTimeIn
9e60: 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 t64().** interfa
9e70: 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 ces are not stri
9e80: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 ctly a part of t
9e90: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 he filesystem, b
9ea0: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 ut they are.** i
9eb0: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 ncluded in the V
9ec0: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 FS structure for
9ed0: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a completeness..*
9ee0: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 * The xRandomnes
9ef0: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 s() function att
9f00: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 empts to return
9f10: 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 nBytes bytes.**
9f20: 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 of good-quality
9f30: 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 randomness into
9f40: 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 zOut. The retur
9f50: 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 n value is.** th
9f60: 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 e actual number
9f70: 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 of bytes of rand
9f80: 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e omness obtained.
9f90: 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 .** The xSleep()
9fa0: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 method causes t
9fb0: 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 he calling threa
9fc0: 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 d to sleep for a
9fd0: 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e t.** least the n
9fe0: 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 umber of microse
9ff0: 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 conds given. ^T
a000: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 he xCurrentTime(
a010: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 ).** method retu
a020: 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 rns a Julian Day
a030: 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 Number for the
a040: 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 current date and
a050: 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c time as.** a fl
a060: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c oating point val
a070: 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 ue..** ^The xCur
a080: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 rentTimeInt64()
a090: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 method returns,
a0a0: 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 as an integer, t
a0b0: 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 he Julian.** Day
a0c0: 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 65 Number multiple
a0d0: 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74 d by 86400000 (t
a0e0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c he number of mil
a0f0: 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a liseconds in .**
a100: 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e a 24-hour day).
a110: 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 .** ^SQLite wi
a120: 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72 ll use the xCurr
a130: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d entTimeInt64() m
a140: 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65 ethod to get the
a150: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 current.** date
a160: 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61 and time if tha
a170: 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69 t method is avai
a180: 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69 lable (if iVersi
a190: 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 on is 2 or .** g
a1a0: 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66 reater and the f
a1b0: 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 unction pointer
a1c0: 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 is not NULL) and
a1d0: 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a will fall back.
a1e0: 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69 ** to xCurrentTi
a1f0: 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74 me() if xCurrent
a200: 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75 TimeInt64() is u
a210: 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a navailable..**.*
a220: 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65 * ^The xSetSyste
a230: 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 mCall(), xGetSys
a240: 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 temCall(), and x
a250: 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 NestSystemCall()
a260: 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 interfaces.** a
a270: 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74 re not used by t
a280: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 he SQLite core.
a290: 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 These optional
a2a0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70 interfaces are p
a2b0: 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f rovided.** by so
a2c0: 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69 me VFSes to faci
a2d0: 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f litate testing o
a2e0: 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20 f the VFS code.
a2f0: 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a By overriding .*
a300: 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 * system calls w
a310: 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e ith functions un
a320: 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c der its control,
a330: 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20 a test program
a340: 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 can.** simulate
a350: 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 faults and error
a360: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 conditions that
a370: 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65 would otherwise
a380: 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a be difficult.**
a390: 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 or impossible t
a3a0: 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73 o induce. The s
a3b0: 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c et of system cal
a3c0: 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f ls that can be o
a3d0: 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 verridden.** var
a3e0: 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 ies from one VFS
a3f0: 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 to another, and
a400: 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f from one versio
a410: 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46 n of the same VF
a420: 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 S to the.** next
a430: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 . Applications
a440: 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69 that use these i
a450: 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62 nterfaces must b
a460: 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 e prepared for a
a470: 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 ny.** or all of
a480: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 these interfaces
a490: 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 to be NULL or f
a4a0: 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f or their behavio
a4b0: 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 r to change.** f
a4c0: 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 rom one release
a4d0: 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70 to the next. Ap
a4e0: 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 plications must
a4f0: 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61 not attempt to a
a500: 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 ccess.** any of
a510: 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66 these methods if
a520: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 the iVersion of
a530: 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73 the VFS is less
a540: 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 than 3..*/.type
a550: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
a560: 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 e3_vfs sqlite3_v
a570: 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64 fs;.typedef void
a580: 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61 (*sqlite3_sysca
a590: 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 ll_ptr)(void);.s
a5a0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 truct sqlite3_vf
a5b0: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 s {. int iVersi
a5c0: 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f on; /
a5d0: 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73 * Structure vers
a5e0: 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 ion number (curr
a5f0: 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e ently 3) */. in
a600: 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 t szOsFile;
a610: 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f /* Size o
a620: 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c f subclassed sql
a630: 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 ite3_file */. i
a640: 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 nt mxPathname;
a650: 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d /* Maxim
a660: 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 um file pathname
a670: 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c length */. sql
a680: 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b ite3_vfs *pNext;
a690: 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 /* Next re
a6a0: 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a gistered VFS */.
a6b0: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e const char *zN
a6c0: 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 ame; /* Na
a6d0: 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 me of this virtu
a6e0: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a al file system *
a6f0: 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 /. void *pAppDa
a700: 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 ta; /*
a710: 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 Pointer to appli
a720: 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 cation-specific
a730: 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a data */. int (*
a740: 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 xOpen)(sqlite3_v
a750: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 fs*, const char
a760: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f *zName, sqlite3_
a770: 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 file*,.
a780: 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c int flags,
a790: 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 int *pOutFlags)
a7a0: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 ;. int (*xDelet
a7b0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c e)(sqlite3_vfs*,
a7c0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
a7d0: 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 me, int syncDir)
a7e0: 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 ;. int (*xAcces
a7f0: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c s)(sqlite3_vfs*,
a800: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
a810: 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 me, int flags, i
a820: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 nt *pResOut);.
a830: 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e int (*xFullPathn
a840: 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ame)(sqlite3_vfs
a850: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
a860: 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 Name, int nOut,
a870: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 char *zOut);. v
a880: 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 oid *(*xDlOpen)(
a890: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
a8a0: 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e nst char *zFilen
a8b0: 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 ame);. void (*x
a8c0: 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 DlError)(sqlite3
a8d0: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 _vfs*, int nByte
a8e0: 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 , char *zErrMsg)
a8f0: 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c ;. void (*(*xDl
a900: 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 Sym)(sqlite3_vfs
a910: 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 *,void*, const c
a920: 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 har *zSymbol))(v
a930: 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 oid);. void (*x
a940: 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 DlClose)(sqlite3
a950: 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 _vfs*, void*);.
a960: 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 int (*xRandomne
a970: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ss)(sqlite3_vfs*
a980: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 , int nByte, cha
a990: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 r *zOut);. int
a9a0: 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 (*xSleep)(sqlite
a9b0: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 3_vfs*, int micr
a9c0: 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 oseconds);. int
a9d0: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 (*xCurrentTime)
a9e0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 (sqlite3_vfs*, d
a9f0: 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 ouble*);. int (
aa00: 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 *xGetLastError)(
aa10: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e sqlite3_vfs*, in
aa20: 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a t, char *);. /*
aa30: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 . ** The method
aa40: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 s above are in v
aa50: 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 ersion 1 of the
aa60: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 sqlite_vfs objec
aa70: 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f t. ** definitio
aa80: 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 n. Those that f
aa90: 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 ollow are added
aaa0: 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 in version 2 or
aab0: 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 later. */. int
aac0: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 (*xCurrentTimeI
aad0: 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 nt64)(sqlite3_vf
aae0: 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 s*, sqlite3_int6
aaf0: 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 4*);. /*. ** T
ab00: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 he methods above
ab10: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 are in versions
ab20: 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 1 and 2 of the
ab30: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 sqlite_vfs objec
ab40: 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 t.. ** Those be
ab50: 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73 low are for vers
ab60: 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65 ion 3 and greate
ab70: 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a r.. */. int (*
ab80: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 xSetSystemCall)(
ab90: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
aba0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
abb0: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c sqlite3_syscall
abc0: 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 _ptr);. sqlite3
abd0: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 _syscall_ptr (*x
abe0: 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 GetSystemCall)(s
abf0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
ac00: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b st char *zName);
ac10: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 . const char *(
ac20: 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c *xNextSystemCall
ac30: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
ac40: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
ac50: 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 e);. /*. ** Th
ac60: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 e methods above
ac70: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 are in versions
ac80: 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74 1 through 3 of t
ac90: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 he sqlite_vfs ob
aca0: 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 ject.. ** New f
acb0: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 ields may be app
acc0: 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 ended in figure
acd0: 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 versions. The i
ace0: 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c Version. ** val
acf0: 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e ue will incremen
ad00: 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 t whenever this
ad10: 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d happens. . */.}
ad20: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
ad30: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 F: Flags for the
ad40: 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 xAccess VFS met
ad50: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 hod.**.** These
ad60: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 integer constant
ad70: 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 s can be used as
ad80: 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d the third param
ad90: 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 eter to.** the x
ada0: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 Access method of
adb0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 an [sqlite3_vfs
adc0: 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 ] object. They
add0: 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 determine.** wha
ade0: 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 t kind of permis
adf0: 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 sions the xAcces
ae00: 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b s method is look
ae10: 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 ing for..** With
ae20: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 SQLITE_ACCESS_E
ae30: 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 XISTS, the xAcce
ae40: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d ss method.** sim
ae50: 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 ply checks wheth
ae60: 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 er the file exis
ae70: 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 ts..** With SQLI
ae80: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 TE_ACCESS_READWR
ae90: 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 ITE, the xAccess
aea0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b method.** check
aeb0: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 s whether the na
aec0: 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 med directory is
aed0: 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 both readable a
aee0: 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 nd writable.** (
aef0: 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 in other words,
af00: 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 if files can be
af10: 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 added, removed,
af20: 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 and renamed with
af30: 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 in.** the direct
af40: 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c ory)..** The SQL
af50: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 ITE_ACCESS_READW
af60: 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 RITE constant is
af70: 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 currently used
af80: 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b only by the.** [
af90: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 temp_store_direc
afa0: 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 tory pragma], th
afb0: 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 ough this could
afc0: 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 change in a futu
afd0: 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 re.** release of
afe0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 SQLite..** With
aff0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 SQLITE_ACCESS_R
b000: 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 EAD, the xAccess
b010: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b method.** check
b020: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 s whether the fi
b030: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 le is readable.
b040: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 The SQLITE_ACCE
b050: 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 SS_READ constant
b060: 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 is.** currently
b070: 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 unused, though
b080: 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 it might be used
b090: 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c in a future rel
b0a0: 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 ease of.** SQLit
b0b0: 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 e..*/.#define SQ
b0c0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 LITE_ACCESS_EXIS
b0d0: 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 TS 0.#define
b0e0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 SQLITE_ACCESS_RE
b0f0: 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 ADWRITE 1 /* U
b100: 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 sed by PRAGMA te
b110: 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f mp_store_directo
b120: 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ry */.#define SQ
b130: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
b140: 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 2 /* Unu
b150: 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 sed */../*.** CA
b160: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f PI3REF: Flags fo
b170: 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 r the xShmLock V
b180: 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 FS method.**.**
b190: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f These integer co
b1a0: 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 nstants define t
b1b0: 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 he various locki
b1c0: 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a ng operations.**
b1d0: 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 allowed by the
b1e0: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 xShmLock method
b1f0: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d of [sqlite3_io_m
b200: 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a ethods]. The.**
b210: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 following are t
b220: 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f he only legal co
b230: 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c mbinations of fl
b240: 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 ags to the.** xS
b250: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a hmLock method:.*
b260: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
b270: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f > SQLITE_SHM_LO
b280: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f CK | SQLITE_SHM_
b290: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 SHARED.** <li>
b2a0: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 SQLITE_SHM_LOCK
b2b0: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 | SQLITE_SHM_EXC
b2c0: 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 LUSIVE.** <li>
b2d0: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 SQLITE_SHM_UNLOC
b2e0: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 K | SQLITE_SHM_S
b2f0: 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 HARED.** <li> S
b300: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b QLITE_SHM_UNLOCK
b310: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 | SQLITE_SHM_EX
b320: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e CLUSIVE.** </ul>
b330: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f .**.** When unlo
b340: 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 cking, the same
b350: 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 SHARED or EXCLUS
b360: 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 IVE flag must be
b370: 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 supplied as.**
b380: 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 was given no the
b390: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c corresponding l
b3a0: 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 ock. .**.** The
b3b0: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 xShmLock method
b3c0: 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 can transition
b3d0: 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 between unlocked
b3e0: 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a and SHARED or.*
b3f0: 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b * between unlock
b400: 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 ed and EXCLUSIVE
b410: 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 . It cannot tra
b420: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 nsition between
b430: 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 SHARED.** and EX
b440: 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 CLUSIVE..*/.#def
b450: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 ine SQLITE_SHM_U
b460: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 NLOCK 1.#d
b470: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d efine SQLITE_SHM
b480: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a _LOCK 2.
b490: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
b4a0: 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 HM_SHARED
b4b0: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
b4c0: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 _SHM_EXCLUSIVE
b4d0: 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 8../*.** CAPI3
b4e0: 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 REF: Maximum xSh
b4f0: 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a mLock index.**.*
b500: 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d * The xShmLock m
b510: 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 ethod on [sqlite
b520: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 3_io_methods] ma
b530: 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 y use values.**
b540: 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 between 0 and th
b550: 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 is upper bound a
b560: 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 s its "offset" a
b570: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 rgument..** The
b580: 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c SQLite core will
b590: 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 never attempt t
b5a0: 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c o acquire or rel
b5b0: 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f ease a.** lock o
b5c0: 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 utside of this r
b5d0: 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ange.*/.#define
b5e0: 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b SQLITE_SHM_NLOCK
b5f0: 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 8.../*.*
b600: 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 * CAPI3REF: Init
b610: 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 ialize The SQLit
b620: 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 e Library.**.**
b630: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 ^The sqlite3_ini
b640: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e tialize() routin
b650: 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 e initializes th
b660: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 e.** SQLite libr
b670: 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 ary. ^The sqlit
b680: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f e3_shutdown() ro
b690: 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 utine.** dealloc
b6a0: 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 ates any resourc
b6b0: 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c es that were all
b6c0: 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 ocated by sqlite
b6d0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 3_initialize()..
b6e0: 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
b6f0: 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 s are designed t
b700: 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 o aid in process
b710: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 initialization
b720: 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 and.** shutdown
b730: 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 on embedded syst
b740: 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f ems. Workstatio
b750: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 n applications u
b760: 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e sing.** SQLite n
b770: 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e ormally do not n
b780: 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 eed to invoke ei
b790: 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f ther of these ro
b7a0: 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 utines..**.** A
b7b0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
b7c0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 initialize() is
b7d0: 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 an "effective" c
b7e0: 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 all if it is.**
b7f0: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 the first time s
b800: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
b810: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 e() is invoked d
b820: 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 uring the lifeti
b830: 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f me of.** the pro
b840: 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 cess, or if it i
b850: 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 s the first time
b860: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
b870: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 ize() is invoked
b880: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 .** following a
b890: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
b8a0: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f shutdown(). ^(O
b8b0: 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 nly an effective
b8c0: 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 call.** of sqli
b8d0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
b8e0: 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 does any initia
b8f0: 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f lization. All o
b900: 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 ther calls.** ar
b910: 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 e harmless no-op
b920: 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c s.)^.**.** A cal
b930: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 l to sqlite3_shu
b940: 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 tdown() is an "e
b950: 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 ffective" call i
b960: 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 f it is the firs
b970: 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c t.** call to sql
b980: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 ite3_shutdown()
b990: 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 since the last s
b9a0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
b9b0: 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 e(). ^(Only.**
b9c0: 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c an effective cal
b9d0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 l to sqlite3_shu
b9e0: 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 tdown() does any
b9f0: 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f deinitializatio
ba00: 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 n..** All other
ba10: 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 valid calls to s
ba20: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
ba30: 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e ) are harmless n
ba40: 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 o-ops.)^.**.** T
ba50: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 he sqlite3_initi
ba60: 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 alize() interfac
ba70: 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c e is threadsafe,
ba80: 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 but sqlite3_shu
ba90: 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f tdown().** is no
baa0: 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f t. The sqlite3_
bab0: 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 shutdown() inter
bac0: 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 face must only b
bad0: 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a e called from a.
bae0: 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 ** single thread
baf0: 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 . All open [dat
bb00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
bb10: 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 s] must be close
bb20: 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 d and all.** oth
bb30: 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 er SQLite resour
bb40: 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c ces must be deal
bb50: 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f located prior to
bb60: 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c invoking.** sql
bb70: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e ite3_shutdown().
bb80: 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 .**.** Among oth
bb90: 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 er things, ^sqli
bba0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
bbb0: 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 will invoke.**
bbc0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
bbd0: 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e ). Similarly, ^
bbe0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
bbf0: 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b ().** will invok
bc00: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 e sqlite3_os_end
bc10: 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ()..**.** ^The s
bc20: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
bc30: 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 e() routine retu
bc40: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 rns [SQLITE_OK]
bc50: 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e on success..** ^
bc60: 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 If for some reas
bc70: 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 on, sqlite3_init
bc80: 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 ialize() is unab
bc90: 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 le to initialize
bca0: 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 .** the library
bcb0: 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75 (perhaps it is u
bcc0: 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 nable to allocat
bcd0: 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 e a needed resou
bce0: 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 rce such.** as a
bcf0: 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72 mutex) it retur
bd00: 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 ns an [error cod
bd10: 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 e] other than [S
bd20: 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a QLITE_OK]..**.**
bd30: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e ^The sqlite3_in
bd40: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 itialize() routi
bd50: 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 ne is called int
bd60: 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 ernally by many
bd70: 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 other.** SQLite
bd80: 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 interfaces so th
bd90: 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f at an applicatio
bda0: 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e n usually does n
bdb0: 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e ot need to.** in
bdc0: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 voke sqlite3_ini
bdd0: 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 tialize() direct
bde0: 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 ly. For example
bdf0: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 , [sqlite3_open(
be00: 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 )].** calls sqli
be10: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
be20: 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c so the SQLite l
be30: 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 ibrary will be a
be40: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 utomatically.**
be50: 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e initialized when
be60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
be70: 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 ] is called if i
be80: 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 t has not be ini
be90: 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 tialized.** alre
bea0: 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 ady. ^However,
beb0: 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d if SQLite is com
bec0: 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b piled with the [
bed0: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f SQLITE_OMIT_AUTO
bee0: 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 INIT].** compile
bef0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 -time option, th
bf00: 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 en the automatic
bf10: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 calls to sqlite
bf20: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 3_initialize().*
bf30: 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e * are omitted an
bf40: 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f d the applicatio
bf50: 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 n must call sqli
bf60: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
bf70: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 directly.** pri
bf80: 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 or to using any
bf90: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 other SQLite int
bfa0: 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 erface. For max
bfb0: 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 imum portability
bfc0: 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d ,.** it is recom
bfd0: 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c mended that appl
bfe0: 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 ications always
bff0: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 invoke sqlite3_i
c000: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 nitialize().** d
c010: 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f irectly prior to
c020: 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 using any other
c030: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
c040: 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 e. Future relea
c050: 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 ses.** of SQLite
c060: 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69 may require thi
c070: 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 s. In other wor
c080: 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 ds, the behavior
c090: 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 exhibited.** wh
c0a0: 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d en SQLite is com
c0b0: 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 piled with [SQLI
c0c0: 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 TE_OMIT_AUTOINIT
c0d0: 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 ] might become t
c0e0: 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 he.** default be
c0f0: 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 havior in some f
c100: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 uture release of
c110: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 SQLite..**.** T
c120: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e he sqlite3_os_in
c130: 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 it() routine doe
c140: 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 s operating-syst
c150: 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 em specific.** i
c160: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 nitialization of
c170: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 the SQLite libr
c180: 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 ary. The sqlite
c190: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 3_os_end().** ro
c1a0: 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 utine undoes the
c1b0: 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 effect of sqlit
c1c0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 e3_os_init(). T
c1d0: 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 ypical tasks.**
c1e0: 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 performed by the
c1f0: 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c se routines incl
c200: 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f ude allocation o
c210: 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a r deallocation.*
c220: 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f * of static reso
c230: 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a urces, initializ
c240: 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 ation of global
c250: 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 variables,.** se
c260: 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 tting up a defau
c270: 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d lt [sqlite3_vfs]
c280: 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 module, or sett
c290: 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 ing up.** a defa
c2a0: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ult configuratio
c2b0: 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 n using [sqlite3
c2c0: 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a _config()]..**.*
c2d0: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f * The applicatio
c2e0: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 n should never i
c2f0: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c nvoke either sql
c300: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a ite3_os_init().*
c310: 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f * or sqlite3_os_
c320: 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 end() directly.
c330: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
c340: 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 should only inv
c350: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 oke.** sqlite3_i
c360: 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 nitialize() and
c370: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
c380: 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 (). The sqlite3
c390: 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e _os_init().** in
c3a0: 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 terface is calle
c3b0: 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 d automatically
c3c0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 by sqlite3_initi
c3d0: 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 alize() and.** s
c3e0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 qlite3_os_end()
c3f0: 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c is called by sql
c400: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e ite3_shutdown().
c410: 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a Appropriate.**
c420: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
c430: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f for sqlite3_os_
c440: 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 init() and sqlit
c450: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 e3_os_end().** a
c460: 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 re built into SQ
c470: 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 Lite when it is
c480: 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 compiled for Uni
c490: 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f x, Windows, or O
c4a0: 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 S/2..** When [cu
c4b0: 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 stom builds | bu
c4c0: 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c ilt for other pl
c4d0: 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 atforms].** (usi
c4e0: 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f ng the [SQLITE_O
c4f0: 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 S_OTHER=1] compi
c500: 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f le-time.** optio
c510: 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 n) the applicati
c520: 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 on must supply a
c530: 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d suitable implem
c540: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 entation for.**
c550: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
c560: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 ) and sqlite3_os
c570: 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c _end(). An appl
c580: 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 ication-supplied
c590: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
c5a0: 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 on of sqlite3_os
c5b0: 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 _init() or sqlit
c5c0: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d e3_os_end().** m
c5d0: 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 ust return [SQLI
c5e0: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 TE_OK] on succes
c5f0: 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 s and some other
c600: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 [error code] up
c610: 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a on.** failure..*
c620: 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
c630: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
c640: 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 ize(void);.SQLIT
c650: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
c660: 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3_shutdown(void)
c670: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
c680: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
c690: 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 (void);.SQLITE_A
c6a0: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f PI int sqlite3_o
c6b0: 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a s_end(void);../*
c6c0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
c6d0: 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 nfiguring The SQ
c6e0: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a Lite Library.**.
c6f0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 ** The sqlite3_c
c700: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 onfig() interfac
c710: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b e is used to mak
c720: 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 e global configu
c730: 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 ration.** change
c740: 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f s to SQLite in o
c750: 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c rder to tune SQL
c760: 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 ite to the speci
c770: 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 fic needs of.**
c780: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e the application.
c790: 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f The default co
c7a0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 nfiguration is r
c7b0: 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d ecommended for m
c7c0: 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 ost.** applicati
c7d0: 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 ons and so this
c7e0: 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c routine is usual
c7f0: 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 ly not necessary
c800: 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 . It is.** prov
c810: 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 ided to support
c820: 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e rare application
c830: 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e s with unusual n
c840: 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 eeds..**.** The
c850: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
c860: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f interface is no
c870: 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 t threadsafe. T
c880: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a he application.*
c890: 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 * must insure th
c8a0: 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 at no other SQLi
c8b0: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 te interfaces ar
c8c0: 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 e invoked by oth
c8d0: 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 er.** threads wh
c8e0: 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ile sqlite3_conf
c8f0: 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e ig() is running.
c900: 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 Furthermore, s
c910: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a qlite3_config().
c920: 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 ** may only be i
c930: 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 nvoked prior to
c940: 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 library initiali
c950: 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 zation using.**
c960: 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c [sqlite3_initial
c970: 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 ize()] or after
c980: 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c shutdown by [sql
c990: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d ite3_shutdown()]
c9a0: 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 ..** ^If sqlite3
c9b0: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c _config() is cal
c9c0: 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 led after [sqlit
c9d0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d e3_initialize()]
c9e0: 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b and before.** [
c9f0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
ca00: 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c ()] then it will
ca10: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d return SQLITE_M
ca20: 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 ISUSE..** Note,
ca30: 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 however, that ^s
ca40: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
ca50: 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 can be called as
ca60: 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 part of the.**
ca70: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
ca80: 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e f an application
ca90: 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 -defined [sqlite
caa0: 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 3_os_init()]..**
cab0: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 .** The first ar
cac0: 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 gument to sqlite
cad0: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 3_config() is an
cae0: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c integer.** [SQL
caf0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c ITE_CONFIG_SINGL
cb00: 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 ETHREAD | config
cb10: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 uration option]
cb20: 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a that determines.
cb30: 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 ** what property
cb40: 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f of SQLite is to
cb50: 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 be configured.
cb60: 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 Subsequent argu
cb70: 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 ments.** vary de
cb80: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b pending on the [
cb90: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 SQLITE_CONFIG_SI
cba0: 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e NGLETHREAD | con
cbb0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
cbc0: 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 n].** in the fir
cbd0: 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a st argument..**.
cbe0: 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 ** ^When a confi
cbf0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 guration option
cc00: 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f is set, sqlite3_
cc10: 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 config() returns
cc20: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a [SQLITE_OK]..**
cc30: 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 ^If the option
cc40: 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 is unknown or SQ
cc50: 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 Lite is unable t
cc60: 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e o set the option
cc70: 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f .** then this ro
cc80: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 utine returns a
cc90: 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 non-zero [error
cca0: 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 code]..*/.SQLITE
ccb0: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
ccc0: 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e _config(int, ...
ccd0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
cce0: 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 EF: Configure da
ccf0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
cd00: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c ns.**.** The sql
cd10: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
cd20: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 interface is us
cd30: 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 ed to make confi
cd40: 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e guration.** chan
cd50: 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 ges to a [databa
cd60: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 se connection].
cd70: 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 The interface i
cd80: 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 s similar to.**
cd90: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
cda0: 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 )] except that t
cdb0: 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 he changes apply
cdc0: 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 to a single.**
cdd0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
cde0: 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 tion] (specified
cdf0: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
ce00: 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 gument)..**.** T
ce10: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
ce20: 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 nt to sqlite3_db
ce30: 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 _config(D,V,...)
ce40: 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c is the.** [SQL
ce50: 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
ce60: 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 KASIDE | configu
ce70: 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 ration verb] - a
ce80: 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a n integer code .
ce90: 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 ** that indicate
cea0: 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 s what aspect of
ceb0: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
cec0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 onnection] is be
ced0: 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a ing configured..
cee0: 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 ** Subsequent ar
cef0: 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 guments vary dep
cf00: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f ending on the co
cf10: 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 nfiguration verb
cf20: 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 ..**.** ^Calls t
cf30: 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e o sqlite3_db_con
cf40: 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c fig() return SQL
cf50: 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e ITE_OK if and on
cf60: 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c ly if.** the cal
cf70: 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 l is considered
cf80: 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 successful..*/.S
cf90: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
cfa0: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
cfb0: 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 sqlite3*, int op
cfc0: 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 , ...);../*.** C
cfd0: 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 API3REF: Memory
cfe0: 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 Allocation Routi
cff0: 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 nes.**.** An ins
d000: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 tance of this ob
d010: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 ject defines the
d020: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 interface betwe
d030: 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 en SQLite.** and
d040: 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 low-level memor
d050: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 y allocation rou
d060: 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 tines..**.** Thi
d070: 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 s object is used
d080: 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 in only one pla
d090: 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 ce in the SQLite
d0a0: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 interface..** A
d0b0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
d0c0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 nstance of this
d0d0: 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 object is the ar
d0e0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 gument to.** [sq
d0f0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
d100: 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 when the configu
d110: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 ration option is
d120: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 .** [SQLITE_CONF
d130: 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 IG_MALLOC] or [S
d140: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
d150: 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 MALLOC]. .** By
d160: 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 creating an ins
d170: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 tance of this ob
d180: 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 ject.** and pass
d190: 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 ing it to [sqlit
d1a0: 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 e3_config]([SQLI
d1b0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 TE_CONFIG_MALLOC
d1c0: 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e ]).** during con
d1d0: 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 figuration, an a
d1e0: 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 pplication can s
d1f0: 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e pecify an altern
d200: 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 ative.** memory
d210: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 allocation subsy
d220: 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 stem for SQLite
d230: 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f to use for all o
d240: 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 f its.** dynamic
d250: 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a memory needs..*
d260: 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 *.** Note that S
d270: 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 QLite comes with
d280: 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d several [built-
d290: 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 in memory alloca
d2a0: 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 tors].** that ar
d2b0: 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 e perfectly adeq
d2c0: 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 uate for the ove
d2d0: 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 rwhelming majori
d2e0: 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f ty of applicatio
d2f0: 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 ns.** and that t
d300: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e his object is on
d310: 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 ly useful to a t
d320: 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 iny minority of
d330: 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 applications.**
d340: 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 with specialized
d350: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
d360: 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e on requirements.
d370: 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 This object is
d380: 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 .** also used du
d390: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 ring testing of
d3a0: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 SQLite in order
d3b0: 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c to specify an al
d3c0: 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d ternative.** mem
d3d0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 ory allocator th
d3e0: 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d at simulates mem
d3f0: 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 ory out-of-memor
d400: 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a y conditions in.
d410: 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 ** order to veri
d420: 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 fy that SQLite r
d430: 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c ecovers graceful
d440: 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 ly from such.**
d450: 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a conditions..**.*
d460: 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 20 61 6e * The xMalloc an
d470: 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 d xFree methods
d480: 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 must work like t
d490: 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 20 61 he.** malloc() a
d4a0: 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 nd free() functi
d4b0: 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 ons from the sta
d4c0: 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e ndard C library.
d4d0: 0a 2a 2a 20 54 68 65 20 78 52 65 61 6c 6c 6f 63 .** The xRealloc
d4e0: 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 77 6f 72 method must wor
d4f0: 6b 20 6c 69 6b 65 20 72 65 61 6c 6c 6f 63 28 29 k like realloc()
d500: 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 from the standa
d510: 72 64 20 43 20 6c 69 62 72 61 72 79 0a 2a 2a 20 rd C library.**
d520: 77 69 74 68 20 74 68 65 20 65 78 63 65 70 74 69 with the excepti
d530: 6f 6e 20 74 68 61 74 20 69 66 20 74 68 65 20 73 on that if the s
d540: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 econd argument t
d550: 6f 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 7a 65 o xRealloc is ze
d560: 72 6f 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 ro,.** xRealloc
d570: 6d 75 73 74 20 62 65 20 61 20 6e 6f 2d 6f 70 20 must be a no-op
d580: 2d 20 69 74 20 6d 75 73 74 20 6e 6f 74 20 70 65 - it must not pe
d590: 72 66 6f 72 6d 20 61 6e 79 20 61 6c 6c 6f 63 61 rform any alloca
d5a0: 74 69 6f 6e 20 6f 72 0a 2a 2a 20 64 65 61 6c 6c tion or.** deall
d5b0: 6f 63 61 74 69 6f 6e 2e 20 20 5e 53 51 4c 69 74 ocation. ^SQLit
d5c0: 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 e guarantees tha
d5d0: 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 t the second arg
d5e0: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 ument to.** xRea
d5f0: 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 lloc is always a
d600: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
d610: 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 by a prior call
d620: 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 20 to xRoundup..**
d630: 41 6e 64 20 73 6f 20 69 6e 20 63 61 73 65 73 20 And so in cases
d640: 77 68 65 72 65 20 78 52 6f 75 6e 64 75 70 20 61 where xRoundup a
d650: 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 lways returns a
d660: 70 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72 2c positive number,
d670: 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 63 61 6e .** xRealloc can
d680: 20 70 65 72 66 6f 72 6d 20 65 78 61 63 74 6c 79 perform exactly
d690: 20 61 73 20 74 68 65 20 73 74 61 6e 64 61 72 64 as the standard
d6a0: 20 6c 69 62 72 61 72 79 20 72 65 61 6c 6c 6f 63 library realloc
d6b0: 28 29 20 61 6e 64 0a 2a 2a 20 73 74 69 6c 6c 20 () and.** still
d6c0: 62 65 20 69 6e 20 63 6f 6d 70 6c 69 61 6e 63 65 be in compliance
d6d0: 20 77 69 74 68 20 74 68 69 73 20 73 70 65 63 69 with this speci
d6e0: 66 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 fication..**.**
d6f0: 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 xSize should ret
d700: 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 urn the allocate
d710: 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f d size of a memo
d720: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a ry allocation.**
d730: 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 previously obta
d740: 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f ined from xMallo
d750: 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 c or xRealloc.
d760: 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 The allocated si
d770: 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 ze.** is always
d780: 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 at least as big
d790: 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 as the requested
d7a0: 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 size but may be
d7b0: 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 larger..**.** T
d7c0: 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 he xRoundup meth
d7d0: 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 od returns what
d7e0: 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c would be the all
d7f0: 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a ocated size of.*
d800: 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 * a memory alloc
d810: 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 ation given a pa
d820: 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 rticular request
d830: 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d ed size. Most m
d840: 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 emory.** allocat
d850: 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d ors round up mem
d860: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 ory allocations
d870: 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 at least to the
d880: 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a next multiple.**
d890: 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c of 8. Some all
d8a0: 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 ocators round up
d8b0: 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c to a larger mul
d8c0: 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f tiple or to a po
d8d0: 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 wer of 2..** Eve
d8e0: 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ry memory alloca
d8f0: 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d tion request com
d900: 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b ing in through [
d910: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
d920: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 ].** or [sqlite3
d930: 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 _realloc()] firs
d940: 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 t calls xRoundup
d950: 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 . If xRoundup r
d960: 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 eturns 0, .** th
d970: 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f at causes the co
d980: 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f rresponding memo
d990: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f ry allocation to
d9a0: 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 fail..**.** The
d9b0: 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e xInit method in
d9c0: 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 itializes the me
d9d0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 mory allocator.
d9e0: 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a (For example,.*
d9f0: 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 * it might alloc
da00: 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 ate any require
da10: 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 mutexes or initi
da20: 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 alize internal d
da30: 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 ata.** structure
da40: 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 s. The xShutdow
da50: 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f n method is invo
da60: 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 ked (indirectly)
da70: 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f by.** [sqlite3_
da80: 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 shutdown()] and
da90: 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 should deallocat
daa0: 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 e any resources
dab0: 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 acquired.** by x
dac0: 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 Init. The pAppD
dad0: 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 ata pointer is u
dae0: 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 sed as the only
daf0: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 parameter to.**
db00: 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 xInit and xShutd
db10: 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 own..**.** SQLit
db20: 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c e holds the [SQL
db30: 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 ITE_MUTEX_STATIC
db40: 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 _MASTER] mutex w
db50: 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a hen it invokes.*
db60: 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 * the xInit meth
db70: 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 od, so the xInit
db80: 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 method need not
db90: 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 be threadsafe.
dba0: 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 The.** xShutdow
dbb0: 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 n method is only
dbc0: 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 called from [sq
dbd0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
dbe0: 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 ] so it does.**
dbf0: 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 not need to be t
dc00: 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 hreadsafe either
dc10: 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 . For all other
dc20: 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 methods, SQLite
dc30: 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 .** holds the [S
dc40: 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 QLITE_MUTEX_STAT
dc50: 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 IC_MEM] mutex as
dc60: 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 long as the.**
dc70: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
dc80: 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 EMSTATUS] config
dc90: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 uration option i
dca0: 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 s turned on (whi
dcb0: 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 ch.** it is by d
dcc0: 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 efault) and so t
dcd0: 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 he methods are a
dce0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 utomatically ser
dcf0: 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 ialized..** Howe
dd00: 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f ver, if [SQLITE_
dd10: 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 CONFIG_MEMSTATUS
dd20: 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 ] is disabled, t
dd30: 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a hen the other.**
dd40: 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 methods must be
dd50: 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 threadsafe or e
dd60: 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f lse make their o
dd70: 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 wn arrangements
dd80: 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 for.** serializa
dd90: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 tion..**.** SQLi
dda0: 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e te will never in
ddb0: 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 voke xInit() mor
ddc0: 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 e than once with
ddd0: 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 out an interveni
dde0: 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 ng.** call to xS
ddf0: 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 hutdown()..*/.ty
de00: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
de10: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
de20: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 sqlite3_mem_met
de30: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c hods;.struct sql
de40: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
de50: 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 {. void *(*xMa
de60: 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 lloc)(int);
de70: 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c /* Memory al
de80: 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f location functio
de90: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 n */. void (*xF
dea0: 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 ree)(void*);
deb0: 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 /* Free a
dec0: 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e prior allocation
ded0: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 */. void *(*xR
dee0: 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e ealloc)(void*,in
def0: 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 t); /* Resize a
df00: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a n allocation */.
df10: 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 int (*xSize)(v
df20: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 oid*);
df30: 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 /* Return the s
df40: 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 ize of an alloca
df50: 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a tion */. int (*
df60: 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 xRoundup)(int);
df70: 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e /* Roun
df80: 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a d up request siz
df90: 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 e to allocation
dfa0: 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a size */. int (*
dfb0: 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 xInit)(void*);
dfc0: 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 /* Init
dfd0: 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 ialize the memor
dfe0: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 y allocator */.
dff0: 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 void (*xShutdow
e000: 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 n)(void*);
e010: 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 /* Deinitialize
e020: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 the memory alloc
e030: 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a ator */. void *
e040: 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 pAppData;
e050: 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 /* Argu
e060: 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 ment to xInit()
e070: 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 and xShutdown()
e080: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.};../*.** CAP
e090: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 I3REF: Configura
e0a0: 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a tion Options.**.
e0b0: 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e ** These constan
e0c0: 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c ts are the avail
e0d0: 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e able integer con
e0e0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
e0f0: 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 ns that.** can b
e100: 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 e passed as the
e110: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
e120: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 o the [sqlite3_c
e130: 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 onfig()] interfa
e140: 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f ce..**.** New co
e150: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
e160: 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 ons may be added
e170: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 in future relea
e180: 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a ses of SQLite..*
e190: 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 * Existing confi
e1a0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 guration options
e1b0: 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e might be discon
e1c0: 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 tinued. Applica
e1d0: 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 tions.** should
e1e0: 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e check the return
e1f0: 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 code from [sqli
e200: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f te3_config()] to
e210: 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a make sure that.
e220: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b ** the call work
e230: 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 ed. The [sqlite
e240: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 3_config()] inte
e250: 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 rface will retur
e260: 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 n a.** non-zero
e270: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 [error code] if
e280: 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f a discontinued o
e290: 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f r unsupported co
e2a0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
e2b0: 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 on.** is invoked
e2c0: 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 ..**.** <dl>.**
e2d0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
e2e0: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f G_SINGLETHREAD</
e2f0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 dt>.** <dd>There
e300: 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 are no argument
e310: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e s to this option
e320: 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 . ^This option
e330: 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 sets the.** [thr
e340: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 eading mode] to
e350: 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 Single-thread.
e360: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 In other words,
e370: 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 it disables.** a
e380: 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 ll mutexing and
e390: 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f puts SQLite into
e3a0: 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 a mode where it
e3b0: 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 can only be use
e3c0: 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 d.** by a single
e3d0: 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 thread. ^If S
e3e0: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
e3f0: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 d with.** the [S
e400: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
e410: 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 | SQLITE_THREAD
e420: 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d SAFE=0] compile-
e430: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e time option then
e440: 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f .** it is not po
e450: 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 ssible to change
e460: 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 the [threading
e470: 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 mode] from its d
e480: 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 efault.** value
e490: 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 of Single-thread
e4a0: 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 and so [sqlite3
e4b0: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 _config()] will
e4c0: 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 return .** [SQLI
e4d0: 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c TE_ERROR] if cal
e4e0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c led with the SQL
e4f0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c ITE_CONFIG_SINGL
e500: 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 ETHREAD.** confi
e510: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e guration option.
e520: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
e530: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
e540: 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a LTITHREAD</dt>.*
e550: 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 * <dd>There are
e560: 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 no arguments to
e570: 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 this option. ^T
e580: 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 his option sets
e590: 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e the.** [threadin
e5a0: 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 g mode] to Multi
e5b0: 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 -thread. In oth
e5c0: 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 er words, it dis
e5d0: 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e ables.** mutexin
e5e0: 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 g on [database c
e5f0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b onnection] and [
e600: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
e610: 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 nt] objects..**
e620: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
e630: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 is responsible f
e640: 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 or serializing a
e650: 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 ccess to.** [dat
e660: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
e670: 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 s] and [prepared
e680: 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 statements]. B
e690: 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 ut other mutexes
e6a0: 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 .** are enabled
e6b0: 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 so that SQLite w
e6c0: 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 ill be safe to u
e6d0: 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 se in a multi-th
e6e0: 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f readed.** enviro
e6f0: 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 nment as long as
e700: 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 no two threads
e710: 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 attempt to use t
e720: 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 he same.** [data
e730: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
e740: 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d at the same tim
e750: 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 e. ^If SQLite i
e760: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a s compiled with.
e770: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 ** the [SQLITE_T
e780: 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 HREADSAFE | SQLI
e790: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d TE_THREADSAFE=0]
e7a0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
e7b0: 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 tion then.** it
e7c0: 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 is not possible
e7d0: 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 to set the Multi
e7e0: 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 -thread [threadi
e7f0: 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 ng mode] and.**
e800: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
e810: 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b )] will return [
e820: 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 SQLITE_ERROR] if
e830: 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 called with the
e840: 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 .** SQLITE_CONFI
e850: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f G_MULTITHREAD co
e860: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
e870: 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c on.</dd>.**.** <
e880: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
e890: 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e _SERIALIZED</dt>
e8a0: 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 .** <dd>There ar
e8b0: 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 e no arguments t
e8c0: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 o this option.
e8d0: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 ^This option set
e8e0: 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 s the.** [thread
e8f0: 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 ing mode] to Ser
e900: 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 ialized. In othe
e910: 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 r words, this op
e920: 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 tion enables.**
e930: 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c all mutexes incl
e940: 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 uding the recurs
e950: 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f ive.** mutexes o
e960: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e n [database conn
e970: 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 ection] and [pre
e980: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
e990: 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 objects..** In
e9a0: 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 this mode (which
e9b0: 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 is the default
e9c0: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 when SQLite is c
e9d0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 ompiled with.**
e9e0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
e9f0: 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 FE=1]) the SQLit
ea00: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 e library will i
ea10: 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 tself serialize
ea20: 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 access.** to [da
ea30: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
ea40: 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 ns] and [prepare
ea50: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f d statements] so
ea60: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 that the.** app
ea70: 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 lication is free
ea80: 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 to use the same
ea90: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
eaa0: 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a ction] or the.**
eab0: 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 same [prepared
eac0: 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 statement] in di
ead0: 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 fferent threads
eae0: 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 at the same time
eaf0: 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 ..** ^If SQLite
eb00: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
eb10: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f .** the [SQLITE_
eb20: 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c THREADSAFE | SQL
eb30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 ITE_THREADSAFE=0
eb40: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
eb50: 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 ption then.** it
eb60: 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 is not possible
eb70: 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 to set the Seri
eb80: 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e alized [threadin
eb90: 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b g mode] and.** [
eba0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
ebb0: 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 ] will return [S
ebc0: 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 QLITE_ERROR] if
ebd0: 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a called with the.
ebe0: 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ** SQLITE_CONFIG
ebf0: 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 _SERIALIZED conf
ec00: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
ec10: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
ec20: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d >SQLITE_CONFIG_M
ec30: 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ALLOC</dt>.** <d
ec40: 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e d> ^(This option
ec50: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
ec60: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 argument which i
ec70: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
ec80: 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 n.** instance of
ec90: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 the [sqlite3_me
eca0: 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 m_methods] struc
ecb0: 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d ture. The argum
ecc0: 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a ent specifies.**
ecd0: 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 alternative low
ece0: 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c -level memory al
ecf0: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 location routine
ed00: 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 s to be used in
ed10: 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 place of.** the
ed20: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
ed30: 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 n routines built
ed40: 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 into SQLite.)^
ed50: 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a ^SQLite makes.**
ed60: 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 its own private
ed70: 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e copy of the con
ed80: 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c tent of the [sql
ed90: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
eda0: 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 ] structure.** b
edb0: 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 efore the [sqlit
edc0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c e3_config()] cal
edd0: 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a l returns.</dd>.
ede0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
edf0: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f _CONFIG_GETMALLO
ee00: 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e C</dt>.** <dd> ^
ee10: 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b (This option tak
ee20: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
ee30: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 ment which is a
ee40: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a pointer to an.**
ee50: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 instance of the
ee60: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 [sqlite3_mem_me
ee70: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 thods] structure
ee80: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f . The [sqlite3_
ee90: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 mem_methods].**
eea0: 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c structure is fil
eeb0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 led with the cur
eec0: 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d rently defined m
eed0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
eee0: 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 routines.)^.**
eef0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 This option can
ef00: 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c be used to overl
ef10: 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 oad the default
ef20: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
ef30: 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 n.** routines wi
ef40: 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61 th a wrapper tha
ef50: 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 t simulations me
ef60: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
ef70: 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 failure or.** tr
ef80: 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 acks memory usag
ef90: 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 e, for example.
efa0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
efb0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 SQLITE_CONFIG_ME
efc0: 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 MSTATUS</dt>.**
efd0: 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f <dd> ^This optio
efe0: 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 n takes single a
eff0: 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 rgument of type
f000: 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 int, interpreted
f010: 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 as a .** boolea
f020: 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 n, which enables
f030: 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 or disables the
f040: 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d collection of m
f050: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
f060: 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e .** statistics.
f070: 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 ^(When memory a
f080: 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 llocation statis
f090: 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 tics are disable
f0a0: 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f d, the .** follo
f0b0: 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 wing SQLite inte
f0c0: 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f rfaces become no
f0d0: 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a n-operational:.*
f0e0: 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c * <ul>.** <l
f0f0: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f i> [sqlite3_memo
f100: 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 ry_used()].**
f110: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 <li> [sqlite3_me
f120: 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 mory_highwater()
f130: 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c ].** <li> [sql
f140: 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c ite3_soft_heap_l
f150: 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c imit64()].** <
f160: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 li> [sqlite3_sta
f170: 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c tus()].** </ul
f180: 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 >)^.** ^Memory a
f190: 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 llocation statis
f1a0: 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 tics are enabled
f1b0: 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 by default unle
f1c0: 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 ss SQLite is.**
f1d0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 compiled with [S
f1e0: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 QLITE_DEFAULT_ME
f1f0: 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 MSTATUS]=0 in wh
f200: 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a ich case memory.
f210: 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 ** allocation st
f220: 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 atistics are dis
f230: 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 abled by default
f240: 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ..** </dd>.**.**
f250: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
f260: 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a IG_SCRATCH</dt>.
f270: 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 ** <dd> ^This op
f280: 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 tion specifies a
f290: 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 static memory b
f2a0: 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 uffer that SQLit
f2b0: 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a e can use for.**
f2c0: 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e scratch memory.
f2d0: 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 There are thre
f2e0: 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 e arguments: A
f2f0: 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 pointer an 8-byt
f300: 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d e.** aligned mem
f310: 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 ory buffer from
f320: 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63 which the scratc
f330: 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 h allocations wi
f340: 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 ll be.** drawn,
f350: 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 the size of each
f360: 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 scratch allocat
f370: 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 ion (sz),.** and
f380: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d the maximum num
f390: 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 ber of scratch a
f3a0: 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 llocations (N).
f3b0: 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d The sz.** argum
f3c0: 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75 ent must be a mu
f3d0: 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a ltiple of 16..**
f3e0: 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
f3f0: 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f ent must be a po
f400: 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 inter to an 8-by
f410: 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 te aligned buffe
f420: 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 r.** of at least
f430: 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d sz*N bytes of m
f440: 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 emory..** ^SQLit
f450: 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f e will use no mo
f460: 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72 61 re than two scra
f470: 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20 tch buffers per
f480: 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e thread. So.** N
f490: 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 should be set t
f4a0: 6f 20 74 77 69 63 65 20 74 68 65 20 65 78 70 65 o twice the expe
f4b0: 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d cted maximum num
f4c0: 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 0a ber of threads..
f4d0: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 ** ^SQLite will
f4e0: 6e 65 76 65 72 20 72 65 71 75 69 72 65 20 61 20 never require a
f4f0: 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74 scratch buffer t
f500: 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e hat is more than
f510: 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 6.** times the
f520: 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69 database page si
f530: 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e ze. ^If SQLite n
f540: 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 eeds needs addit
f550: 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 ional.** scratch
f560: 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 memory beyond w
f570: 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 hat is provided
f580: 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 by this configur
f590: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 ation option, th
f5a0: 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f en .** [sqlite3_
f5b0: 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 malloc()] will b
f5c0: 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e e used to obtain
f5d0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 the memory need
f5e0: 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c ed.</dd>.**.** <
f5f0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
f600: 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a _PAGECACHE</dt>.
f610: 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 ** <dd> ^This op
f620: 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 tion specifies a
f630: 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 static memory b
f640: 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 uffer that SQLit
f650: 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a e can use for.**
f660: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 the database pa
f670: 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 ge cache with th
f680: 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 e default page c
f690: 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 61 74 69 ache implemenati
f6a0: 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f on. .** This co
f6b0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 nfiguration shou
f6c0: 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 ld not be used i
f6d0: 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e f an application
f6e0: 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 -define page.**
f6f0: 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 cache implementa
f700: 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 tion is loaded u
f710: 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f sing the SQLITE_
f720: 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 6f 70 CONFIG_PCACHE op
f730: 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 tion..** There a
f740: 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e re three argumen
f750: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f ts to this optio
f760: 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 n: A pointer to
f770: 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 8-byte aligned.*
f780: 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 * memory, the si
f790: 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 ze of each page
f7a0: 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 buffer (sz), and
f7b0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 the number of p
f7c0: 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 ages (N)..** The
f7d0: 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f sz argument sho
f7e0: 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 uld be the size
f7f0: 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 of the largest d
f800: 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 atabase page.**
f810: 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 (a power of two
f820: 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 between 512 and
f830: 33 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 32768) plus a li
f840: 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 ttle extra for e
f850: 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 ach.** page head
f860: 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68 er. ^The page h
f870: 65 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 eader size is 20
f880: 20 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 to 40 bytes dep
f890: 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 ending on.** the
f8a0: 20 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 host architectu
f8b0: 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d re. ^It is harm
f8c0: 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d less, apart from
f8d0: 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f the wasted memo
f8e0: 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 ry,.** to make s
f8f0: 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c z a little too l
f900: 61 72 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 arge. The first
f910: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f .** argument sho
f920: 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 uld point to an
f930: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 allocation of at
f940: 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 least sz*N byte
f950: 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 s of memory..**
f960: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 ^SQLite will use
f970: 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 the memory prov
f980: 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73 ided by the firs
f990: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 t argument to sa
f9a0: 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d tisfy its.** mem
f9b0: 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 ory needs for th
f9c0: 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 e first N pages
f9d0: 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 that it adds to
f9e0: 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 cache. ^If addi
f9f0: 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 tional.** page c
fa00: 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e ache memory is n
fa10: 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 eeded beyond wha
fa20: 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 t is provided by
fa30: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 this option, th
fa40: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 en.** SQLite goe
fa50: 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 s to [sqlite3_ma
fa60: 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 lloc()] for the
fa70: 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 additional stora
fa80: 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 ge space..** The
fa90: 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 pointer in the
faa0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d first argument m
fab0: 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 ust.** be aligne
fac0: 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 d to an 8-byte b
fad0: 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 oundary or subse
fae0: 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f quent behavior o
faf0: 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c f SQLite.** will
fb00: 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f be undefined.</
fb10: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
fb20: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 LITE_CONFIG_HEAP
fb30: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 </dt>.** <dd> ^T
fb40: 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 his option speci
fb50: 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 fies a static me
fb60: 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 mory buffer that
fb70: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 SQLite will use
fb80: 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 .** for all of i
fb90: 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 ts dynamic memor
fba0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 y allocation nee
fbb0: 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 ds beyond those
fbc0: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 provided.** for
fbd0: 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 by [SQLITE_CONFI
fbe0: 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b G_SCRATCH] and [
fbf0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 SQLITE_CONFIG_PA
fc00: 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 GECACHE]..** The
fc10: 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 re are three arg
fc20: 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 uments: An 8-byt
fc30: 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 e aligned pointe
fc40: 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c r to the memory,
fc50: 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f .** the number o
fc60: 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d f bytes in the m
fc70: 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e emory buffer, an
fc80: 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c d the minimum al
fc90: 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a location size..*
fca0: 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 * ^If the first
fcb0: 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d pointer (the mem
fcc0: 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 ory pointer) is
fcd0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 NULL, then SQLit
fce0: 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 e reverts.** to
fcf0: 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c using its defaul
fd00: 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 t memory allocat
fd10: 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d or (the system m
fd20: 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e alloc() implemen
fd30: 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f tation),.** undo
fd40: 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e ing any prior in
fd50: 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c vocation of [SQL
fd60: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f ITE_CONFIG_MALLO
fd70: 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 C]. ^If the.**
fd80: 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 memory pointer i
fd90: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 s not NULL and e
fda0: 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e ither [SQLITE_EN
fdb0: 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 ABLE_MEMSYS3] or
fdc0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 .** [SQLITE_ENAB
fdd0: 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 LE_MEMSYS5] are
fde0: 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 defined, then th
fdf0: 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 e alternative me
fe00: 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f mory.** allocato
fe10: 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 r is engaged to
fe20: 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 handle all of SQ
fe30: 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c Lites memory all
fe40: 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a ocation needs..*
fe50: 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e * The first poin
fe60: 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 ter (the memory
fe70: 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 pointer) must be
fe80: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 aligned to an 8
fe90: 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 -byte.** boundar
fea0: 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 y or subsequent
feb0: 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 behavior of SQLi
fec0: 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 te will be undef
fed0: 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e ined..** The min
fee0: 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 imum allocation
fef0: 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 size is capped a
ff00: 74 20 32 5e 31 32 2e 20 52 65 61 73 6f 6e 61 62 t 2^12. Reasonab
ff10: 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 le values.** for
ff20: 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c the minimum all
ff30: 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 ocation size are
ff40: 20 32 5e 35 20 74 68 72 6f 75 67 68 20 32 5e 38 2^5 through 2^8
ff50: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
ff60: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d >SQLITE_CONFIG_M
ff70: 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 UTEX</dt>.** <dd
ff80: 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 > ^(This option
ff90: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
ffa0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
ffb0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
ffc0: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 .** instance of
ffd0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 the [sqlite3_mut
ffe0: 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 ex_methods] stru
fff0: 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 cture. The argu
10000 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a ment specifies.*
10010 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f * alternative lo
10020 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f w-level mutex ro
10030 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 utines to be use
10040 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 d in place.** th
10050 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 e mutex routines
10060 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 built into SQLi
10070 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d te.)^ ^SQLite m
10080 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 akes a copy of t
10090 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 he.** content of
100a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 the [sqlite3_mu
100b0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 tex_methods] str
100c0 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 ucture before th
100d0 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 e call to.** [sq
100e0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
100f0 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c returns. ^If SQL
10100 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
10110 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c with.** the [SQL
10120 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c ITE_THREADSAFE |
10130 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 SQLITE_THREADSA
10140 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 FE=0] compile-ti
10150 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a me option then.*
10160 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 * the entire mut
10170 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 exing subsystem
10180 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 is omitted from
10190 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 the build and he
101a0 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 nce calls to.**
101b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
101c0 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 )] with the SQLI
101d0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 TE_CONFIG_MUTEX
101e0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
101f0 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 tion will.** ret
10200 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f urn [SQLITE_ERRO
10210 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c R].</dd>.**.** <
10220 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
10230 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a _GETMUTEX</dt>.*
10240 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 * <dd> ^(This op
10250 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e tion takes a sin
10260 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 gle argument whi
10270 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 ch is a pointer
10280 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 to an.** instanc
10290 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 e of the [sqlite
102a0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 3_mutex_methods]
102b0 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 structure. The
102c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 .** [sqlite3_mut
102d0 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 ex_methods].** s
102e0 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c tructure is fill
102f0 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 ed with the curr
10300 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 ently defined mu
10310 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a tex routines.)^.
10320 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 ** This option c
10330 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 an be used to ov
10340 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 erload the defau
10350 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 lt mutex allocat
10360 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 ion.** routines
10370 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 with a wrapper u
10380 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 sed to track mut
10390 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 ex usage for per
103a0 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 formance.** prof
103b0 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 iling or testing
103c0 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 , for example.
103d0 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 ^If SQLite is c
103e0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 ompiled with.**
103f0 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 the [SQLITE_THRE
10400 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f ADSAFE | SQLITE_
10410 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f THREADSAFE=0] co
10420 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
10430 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e n then.** the en
10440 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 tire mutexing su
10450 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 bsystem is omitt
10460 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c ed from the buil
10470 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c d and hence call
10480 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 s to.** [sqlite3
10490 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 _config()] with
104a0 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 the SQLITE_CONFI
104b0 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 G_GETMUTEX confi
104c0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 guration option
104d0 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b will.** return [
104e0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f SQLITE_ERROR].</
104f0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
10500 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b LITE_CONFIG_LOOK
10510 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ASIDE</dt>.** <d
10520 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e d> ^(This option
10530 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d takes two argum
10540 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d ents that determ
10550 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a ine the default.
10560 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ** memory alloca
10570 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f tion for the loo
10580 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c kaside memory al
10590 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a locator on each.
105a0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
105b0 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 nection]. The f
105c0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 irst argument is
105d0 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 the.** size of
105e0 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 each lookaside b
105f0 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 uffer slot and t
10600 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 he second is the
10610 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c number of.** sl
10620 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f ots allocated to
10630 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 each database c
10640 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 onnection.)^ ^(
10650 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 This option sets
10660 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 the.** <i>defau
10670 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 lt</i> lookaside
10680 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 size. The [SQLI
10690 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b TE_DBCONFIG_LOOK
106a0 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 ASIDE].** verb t
106b0 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f o [sqlite3_db_co
106c0 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 nfig()] can be u
106d0 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 sed to change th
106e0 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 e lookaside.** c
106f0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 onfiguration on
10700 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 individual conne
10710 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a ctions.)^ </dd>.
10720 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
10730 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 3c 2f _CONFIG_PCACHE</
10740 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 dt>.** <dd> ^(Th
10750 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 is option takes
10760 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
10770 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 t which is a poi
10780 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 nter to.** an [s
10790 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 qlite3_pcache_me
107a0 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 thods] object.
107b0 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 This object spec
107c0 69 66 69 65 73 20 74 68 65 20 69 6e 74 65 72 66 ifies the interf
107d0 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 ace.** to a cust
107e0 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d om page cache im
107f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 plementation.)^
10800 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 ^SQLite makes a
10810 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 copy of the.**
10820 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20 object and uses
10830 69 74 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 it for page cach
10840 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
10850 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ions.</dd>.**.**
10860 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
10870 49 47 5f 47 45 54 50 43 41 43 48 45 3c 2f 64 74 IG_GETPCACHE</dt
10880 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 >.** <dd> ^(This
10890 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
108a0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
108b0 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 which is a point
108c0 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c er to an.** [sql
108d0 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 ite3_pcache_meth
108e0 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 ods] object. SQ
108f0 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 Lite copies of t
10900 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 he current.** pa
10910 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 ge cache impleme
10920 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 ntation into tha
10930 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 t object.)^ </dd
10940 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
10950 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 TE_CONFIG_LOG</d
10960 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 t>.** <dd> ^The
10970 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f SQLITE_CONFIG_LO
10980 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 G option takes t
10990 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 wo arguments: a
109a0 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 pointer to a.**
109b0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 function with a
109c0 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f call signature o
109d0 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c f void(*)(void*,
109e0 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 int,const char*)
109f0 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e , .** and a poin
10a00 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 ter to void. ^If
10a10 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f the function po
10a20 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c inter is not NUL
10a30 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f L, it is.** invo
10a40 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ked by [sqlite3_
10a50 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 log()] to proces
10a60 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 s each logging e
10a70 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a vent. ^If the.*
10a80 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 * function point
10a90 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 er is NULL, the
10aa0 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 [sqlite3_log()]
10ab0 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 interface become
10ac0 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 s a no-op..** ^T
10ad0 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 he void pointer
10ae0 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f that is the seco
10af0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 nd argument to S
10b00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 QLITE_CONFIG_LOG
10b10 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 is.** passed th
10b20 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 rough as the fir
10b30 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 st parameter to
10b40 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
10b50 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a defined logger.*
10b60 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 * function whene
10b70 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f ver that functio
10b80 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e n is invoked. ^
10b90 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
10ba0 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c eter to.** the l
10bb0 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 ogger function i
10bc0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 s a copy of the
10bd0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
10be0 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e to the correspon
10bf0 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ding.** [sqlite3
10c00 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 _log()] call and
10c10 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 is intended to
10c20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 be a [result cod
10c30 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 e] or an.** [ext
10c40 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
10c50 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 e]. ^The third
10c60 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 parameter passed
10c70 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 to the logger i
10c80 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 s.** log message
10c90 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e after formattin
10ca0 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 g via [sqlite3_s
10cb0 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 nprintf()]..** T
10cc0 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e he SQLite loggin
10cd0 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e g interface is n
10ce0 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 ot reentrant; th
10cf0 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f e logger functio
10d00 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 n.** supplied by
10d10 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
10d20 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 must not invoke
10d30 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 any SQLite inte
10d40 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d rface..** In a m
10d50 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 ulti-threaded ap
10d60 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 plication, the a
10d70 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
10d80 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e ed logger.** fun
10d90 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 ction must be th
10da0 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a readsafe. </dd>.
10db0 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 **.** </dl>.*/.#
10dc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
10dd0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 NFIG_SINGLETHREA
10de0 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a D 1 /* nil */.
10df0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
10e00 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 ONFIG_MULTITHREA
10e10 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f D 2 /* nil */
10e20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
10e30 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 CONFIG_SERIALIZE
10e40 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a D 3 /* nil *
10e50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
10e60 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 _CONFIG_MALLOC
10e70 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 4 /* sqli
10e80 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a te3_mem_methods*
10e90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
10ea0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c TE_CONFIG_GETMAL
10eb0 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 LOC 5 /* sq
10ec0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
10ed0 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 s* */.#define SQ
10ee0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 LITE_CONFIG_SCRA
10ef0 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 TCH 6 /*
10f00 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 void*, int sz, i
10f10 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 nt N */.#define
10f20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 SQLITE_CONFIG_PA
10f30 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f GECACHE 7 /
10f40 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c * void*, int sz,
10f50 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e int N */.#defin
10f60 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
10f70 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20 HEAP 8
10f80 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e /* void*, int n
10f90 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f Byte, int min */
10fa0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
10fb0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 CONFIG_MEMSTATUS
10fc0 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 9 /* boole
10fd0 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 an */.#define SQ
10fe0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 LITE_CONFIG_MUTE
10ff0 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 X 10 /*
11000 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 sqlite3_mutex_me
11010 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e thods* */.#defin
11020 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
11030 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 GETMUTEX 11
11040 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 /* sqlite3_mute
11050 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a x_methods* */./*
11060 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 previously SQLI
11070 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 TE_CONFIG_CHUNKA
11080 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 LLOC 12 which is
11090 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 now unused. */
110a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
110b0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
110c0 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 13 /* int i
110d0 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 nt */.#define SQ
110e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
110f0 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 HE 14 /*
11100 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d sqlite3_pcache_m
11110 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 ethods* */.#defi
11120 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
11130 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 _GETPCACHE 15
11140 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 /* sqlite3_pca
11150 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a che_methods* */.
11160 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
11170 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 ONFIG_LOG
11180 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 16 /* xFunc,
11190 20 76 6f 69 64 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a void* */../*.**
111a0 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 CAPI3REF: Datab
111b0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 ase Connection C
111c0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 onfiguration Opt
111d0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ions.**.** These
111e0 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 constants are t
111f0 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 he available int
11200 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 eger configurati
11210 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a on options that.
11220 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 ** can be passed
11230 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 as the second a
11240 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b rgument to the [
11250 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
11260 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a g()] interface..
11270 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 **.** New config
11280 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 uration options
11290 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 may be added in
112a0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 future releases
112b0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 of SQLite..** Ex
112c0 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 isting configura
112d0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 tion options mig
112e0 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 ht be discontinu
112f0 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e ed. Application
11300 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 s.** should chec
11310 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 k the return cod
11320 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f e from [sqlite3_
11330 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 db_config()] to
11340 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a make sure that.*
11350 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 * the call worke
11360 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 d. ^The [sqlite
11370 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 3_db_config()] i
11380 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 nterface will re
11390 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 turn a.** non-ze
113a0 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 ro [error code]
113b0 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 if a discontinue
113c0 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 d or unsupported
113d0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
113e0 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f ption.** is invo
113f0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a ked..**.** <dl>.
11400 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 ** <dt>SQLITE_DB
11410 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
11420 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 </dt>.** <dd> ^T
11430 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
11440 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 three additiona
11450 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 l arguments that
11460 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a determine the .
11470 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 ** [lookaside me
11480 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 mory allocator]
11490 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f configuration fo
114a0 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 r the [database
114b0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 connection]..**
114c0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d ^The first argum
114d0 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70 ent (the third p
114e0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c arameter to [sql
114f0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
11500 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 ] is a.** pointe
11510 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 r to a memory bu
11520 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 ffer to use for
11530 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 lookaside memory
11540 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 ..** ^The first
11550 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 argument after t
11560 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 he SQLITE_DBCONF
11570 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 IG_LOOKASIDE ver
11580 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c b.** may be NULL
11590 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 in which case S
115a0 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 QLite will alloc
115b0 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 ate the.** looka
115c0 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65 side buffer itse
115d0 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 lf using [sqlite
115e0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 3_malloc()]. ^Th
115f0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
11600 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 t is the.** size
11610 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 of each lookasi
11620 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 de buffer slot.
11630 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 ^The third argu
11640 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 ment is the numb
11650 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 er of.** slots.
11660 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 The size of the
11670 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 buffer in the f
11680 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 irst argument mu
11690 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68 st be greater th
116a0 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 an.** or equal t
116b0 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 o the product of
116c0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 the second and
116d0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e third arguments.
116e0 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 The buffer.**
116f0 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 must be aligned
11700 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 to an 8-byte bou
11710 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 ndary. ^If the
11720 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
11730 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 to.** SQLITE_DBC
11740 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 ONFIG_LOOKASIDE
11750 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c is not a multipl
11760 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e e of 8, it is in
11770 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e ternally.** roun
11780 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 ded down to the
11790 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c next smaller mul
117a0 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 tiple of 8. ^(T
117b0 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d he lookaside mem
117c0 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 ory.** configura
117d0 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 tion for a datab
117e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 ase connection c
117f0 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 an only be chang
11800 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 ed when that.**
11810 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f connection is no
11820 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e t currently usin
11830 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f g lookaside memo
11840 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 ry, or in other
11850 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 words.** when th
11860 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 e "current value
11870 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a " returned by.**
11880 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 [sqlite3_db_sta
11890 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 tus](D,[SQLITE_C
118a0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d ONFIG_LOOKASIDE]
118b0 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a ,...) is zero..*
118c0 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f * Any attempt to
118d0 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b change the look
118e0 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e aside memory con
118f0 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 figuration when
11900 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d lookaside.** mem
11910 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 ory is in use le
11920 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 aves the configu
11930 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 ration unchanged
11940 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a and returns .**
11950 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 [SQLITE_BUSY].)
11960 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 ^</dd>.**.** <dt
11970 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 >SQLITE_DBCONFIG
11980 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 _ENABLE_FKEY</dt
11990 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 >.** <dd> ^This
119a0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 option is used t
119b0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 o enable or disa
119c0 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d ble the enforcem
119d0 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 ent of.** [forei
119e0 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e gn key constrain
119f0 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 ts]. There shou
11a00 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 ld be two additi
11a10 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a onal arguments..
11a20 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 ** The first arg
11a30 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 ument is an inte
11a40 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 ger which is 0 t
11a50 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 o disable FK enf
11a60 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 orcement,.** pos
11a70 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 itive to enable
11a80 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f FK enforcement o
11a90 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 r negative to le
11aa0 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 ave FK enforceme
11ab0 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e nt.** unchanged.
11ac0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 The second par
11ad0 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e ameter is a poin
11ae0 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 ter to an intege
11af0 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 r into which.**
11b00 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 is written 0 or
11b10 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 1 to indicate wh
11b20 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 ether FK enforce
11b30 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f ment is off or o
11b40 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 n.** following t
11b50 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 his call. The s
11b60 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
11b70 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f may be a NULL po
11b80 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 inter, in.** whi
11b90 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 ch case the FK e
11ba0 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 nforcement setti
11bb0 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 ng is not report
11bc0 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a ed back. </dd>.*
11bd0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
11be0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f DBCONFIG_ENABLE_
11bf0 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 TRIGGER</dt>.**
11c00 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f <dd> ^This optio
11c10 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 n is used to ena
11c20 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b ble or disable [
11c30 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c CREATE TRIGGER |
11c40 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 triggers]..** T
11c50 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 here should be t
11c60 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 wo additional ar
11c70 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 guments..** The
11c80 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 first argument i
11c90 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 s an integer whi
11ca0 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 ch is 0 to disab
11cb0 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 le triggers,.**
11cc0 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 positive to enab
11cd0 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e le triggers or n
11ce0 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 egative to leave
11cf0 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 the setting unc
11d00 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 hanged..** The s
11d10 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
11d20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
11d30 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 an integer into
11d40 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 which.** is writ
11d50 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e ten 0 or 1 to in
11d60 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74 dicate whether t
11d70 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61 riggers are disa
11d80 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a bled or enabled.
11d90 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 ** following thi
11da0 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 s call. The sec
11db0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 ond parameter ma
11dc0 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e y be a NULL poin
11dd0 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 ter, in.** which
11de0 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65 case the trigge
11df0 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 r setting is not
11e00 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 reported back.
11e10 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c </dd>.**.** </dl
11e20 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c >.*/.#define SQL
11e30 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
11e40 4b 41 53 49 44 45 20 20 20 20 20 20 20 31 30 30 KASIDE 100
11e50 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 1 /* void* int
11e60 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 int */.#define S
11e70 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 QLITE_DBCONFIG_E
11e80 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 NABLE_FKEY 1
11e90 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 002 /* int int*
11ea0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
11eb0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 TE_DBCONFIG_ENAB
11ec0 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30 30 33 LE_TRIGGER 1003
11ed0 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f /* int int* */
11ee0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 .../*.** CAPI3RE
11ef0 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 F: Enable Or Dis
11f00 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 able Extended Re
11f10 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a sult Codes.**.**
11f20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 ^The sqlite3_ex
11f30 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f tended_result_co
11f40 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e des() routine en
11f50 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 ables or disable
11f60 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 s the.** [extend
11f70 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d ed result codes]
11f80 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 feature of SQLi
11f90 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 te. ^The extende
11fa0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 d result.** code
11fb0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 s are disabled b
11fc0 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 y default for hi
11fd0 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 storical compati
11fe0 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54 bility..*/.SQLIT
11ff0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
12000 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 3_extended_resul
12010 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a t_codes(sqlite3*
12020 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f , int onoff);../
12030 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c *.** CAPI3REF: L
12040 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 ast Insert Rowid
12050 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 .**.** ^Each ent
12060 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 ry in an SQLite
12070 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 table has a uniq
12080 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 ue 64-bit signed
12090 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 .** integer key
120a0 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 called the [ROWI
120b0 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 D | "rowid"]. ^T
120c0 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 he rowid is alwa
120d0 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 ys available.**
120e0 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 as an undeclared
120f0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f column named RO
12100 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f WID, OID, or _RO
12110 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 WID_ as long as
12120 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 those.** names a
12130 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 re not also used
12140 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 by explicitly d
12150 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e eclared columns.
12160 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c ^If.** the tabl
12170 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f e has a column o
12180 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 f type [INTEGER
12190 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 PRIMARY KEY] the
121a0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a n that column.**
121b0 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 is another alia
121c0 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e s for the rowid.
121d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 .**.** ^This rou
121e0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 tine returns the
121f0 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 [rowid] of the
12200 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 most recent.** s
12210 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 uccessful [INSER
12220 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 T] into the data
12230 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 base from the [d
12240 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
12250 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 on].** in the fi
12260 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e rst argument. ^
12270 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c If no successful
12280 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61 [INSERT]s.** ha
12290 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 ve ever occurred
122a0 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61 73 on that databas
122b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 e connection, ze
122c0 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a ro is returned..
122d0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 **.** ^(If an [I
122e0 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 NSERT] occurs wi
122f0 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 thin a trigger,
12300 74 68 65 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d then the [rowid]
12310 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 of the inserted
12320 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65 74 75 72 .** row is retur
12330 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 ned by this rout
12340 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 ine as long as t
12350 68 65 20 74 72 69 67 67 65 72 20 69 73 20 72 75 he trigger is ru
12360 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e nning..** But on
12370 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 74 ce the trigger t
12380 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76 erminates, the v
12390 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 alue returned by
123a0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a this routine.**
123b0 20 72 65 76 65 72 74 73 20 74 6f 20 74 68 65 20 reverts to the
123c0 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72 last value inser
123d0 74 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 74 ted before the t
123e0 72 69 67 67 65 72 20 66 69 72 65 64 2e 29 5e 0a rigger fired.)^.
123f0 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 **.** ^An [INSER
12400 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 T] that fails du
12410 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e e to a constrain
12420 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e t violation is n
12430 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 ot a.** successf
12440 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 ul [INSERT] and
12450 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 does not change
12460 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
12470 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f ed by this.** ro
12480 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e utine. ^Thus IN
12490 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e SERT OR FAIL, IN
124a0 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 SERT OR IGNORE,
124b0 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 INSERT OR ROLLBA
124c0 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 CK,.** and INSER
124d0 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 T OR ABORT make
124e0 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 no changes to th
124f0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f e return value o
12500 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e f this.** routin
12510 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 e when their ins
12520 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e ertion fails. ^
12530 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 (When INSERT OR
12540 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 REPLACE.** encou
12550 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 nters a constrai
12560 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 nt violation, it
12570 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 does not fail.
12580 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 The.** INSERT c
12590 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 ontinues to comp
125a0 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c letion after del
125b0 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 eting rows that
125c0 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f caused.** the co
125d0 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d nstraint problem
125e0 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 so INSERT OR RE
125f0 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 PLACE will alway
12600 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 s change.** the
12610 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 return value of
12620 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 this interface.)
12630 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 ^.**.** ^For the
12640 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 purposes of thi
12650 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 s routine, an [I
12660 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 NSERT] is consid
12670 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 ered to.** be su
12680 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 ccessful even if
12690 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e it is subsequen
126a0 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e tly rolled back.
126b0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 .**.** This func
126c0 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 tion is accessib
126d0 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d le to SQL statem
126e0 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 ents via the.**
126f0 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 [last_insert_row
12700 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f id() SQL functio
12710 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 n]..**.** If a s
12720 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 eparate thread p
12730 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 erforms a new [I
12740 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 NSERT] on the sa
12750 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 me.** database c
12760 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 onnection while
12770 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 the [sqlite3_las
12780 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 t_insert_rowid()
12790 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 ].** function is
127a0 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 running and thu
127b0 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 s changes the la
127c0 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 st insert [rowid
127d0 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 ],.** then the v
127e0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 alue returned by
127f0 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 [sqlite3_last_i
12800 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 nsert_rowid()] i
12810 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 s.** unpredictab
12820 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 le and might not
12830 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 equal either th
12840 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 e old or the new
12850 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 .** last insert
12860 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 [rowid]..*/.SQLI
12870 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 TE_API sqlite3_i
12880 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 nt64 sqlite3_las
12890 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 t_insert_rowid(s
128a0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
128b0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 CAPI3REF: Count
128c0 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 The Number Of R
128d0 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a ows Modified.**.
128e0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f ** ^This functio
128f0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 n returns the nu
12900 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 mber of database
12910 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 rows that were
12920 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e changed.** or in
12930 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 serted or delete
12940 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 d by the most re
12950 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 cently completed
12960 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a SQL statement.*
12970 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 * on the [databa
12980 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 se connection] s
12990 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 pecified by the
129a0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e first parameter.
129b0 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 .** ^(Only chang
129c0 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65 es that are dire
129d0 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 ctly specified b
129e0 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 y the [INSERT],
129f0 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 [UPDATE],.** or
12a00 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 [DELETE] stateme
12a10 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 nt are counted.
12a20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 Auxiliary chang
12a30 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 es caused by.**
12a40 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 triggers or [for
12a50 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 eign key actions
12a60 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 ] are not counte
12a70 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 d.)^ Use the.**
12a80 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 [sqlite3_total_c
12a90 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 hanges()] functi
12aa0 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 on to find the t
12ab0 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 otal number of c
12ac0 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 hanges.** includ
12ad0 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 ing changes caus
12ae0 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61 ed by triggers a
12af0 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 nd foreign key a
12b00 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 ctions..**.** ^C
12b10 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 hanges to a view
12b20 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61 that are simula
12b30 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 ted by an [INSTE
12b40 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a AD OF trigger].*
12b50 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 * are not counte
12b60 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 d. Only real ta
12b70 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 ble changes are
12b80 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e counted..**.** ^
12b90 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 (A "row change"
12ba0 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 is a change to a
12bb0 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 single row of a
12bc0 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a single table.**
12bd0 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e caused by an IN
12be0 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 SERT, DELETE, or
12bf0 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e UPDATE statemen
12c00 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a t. Rows that.**
12c10 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 are changed as
12c20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 side effects of
12c30 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 [REPLACE] constr
12c40 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c aint resolution,
12c50 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 .** rollback, AB
12c60 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 ORT processing,
12c70 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 [DROP TABLE], or
12c80 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a by any other.**
12c90 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e mechanisms do n
12ca0 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 ot count as dire
12cb0 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 ct row changes.)
12cc0 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 ^.**.** A "trigg
12cd0 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 er context" is a
12ce0 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 scope of execut
12cf0 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 ion that begins
12d00 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 and.** ends with
12d10 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 the script of a
12d20 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 [CREATE TRIGGER
12d30 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a | trigger]. .**
12d40 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d Most SQL statem
12d50 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c ents are.** eval
12d60 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 uated outside of
12d70 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 any trigger. T
12d80 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 his is the "top
12d90 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 level".** trigge
12da0 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 r context. If a
12db0 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66 trigger fires f
12dc0 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 rom the top leve
12dd0 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 l, a.** new trig
12de0 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 ger context is e
12df0 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 ntered for the d
12e00 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 uration of that
12e10 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 one.** trigger.
12e20 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65 Subtriggers cre
12e30 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 ate subcontexts
12e40 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69 for their durati
12e50 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 on..**.** ^Calli
12e60 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 ng [sqlite3_exec
12e70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
12e80 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 step()] recursiv
12e90 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 ely does.** not
12ea0 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 create a new tri
12eb0 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a gger context..**
12ec0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 .** ^This functi
12ed0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e on returns the n
12ee0 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 umber of direct
12ef0 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 row changes in t
12f00 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e he.** most recen
12f10 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 t INSERT, UPDATE
12f20 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 , or DELETE stat
12f30 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 ement within the
12f40 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 same.** trigger
12f50 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 context..**.**
12f60 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c ^Thus, when call
12f70 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 ed from the top
12f80 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 level, this func
12f90 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 tion returns the
12fa0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 .** number of ch
12fb0 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 anges in the mos
12fc0 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c t recent INSERT,
12fd0 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 UPDATE, or DELE
12fe0 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 TE.** that also
12ff0 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20 occurred at the
13000 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 top level. ^(Wi
13010 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 thin the body of
13020 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 a trigger,.** t
13030 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 he sqlite3_chang
13040 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 es() interface c
13050 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 an be called to
13060 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 find the number
13070 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e of.** changes in
13080 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
13090 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 ly completed INS
130a0 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 ERT, UPDATE, or
130b0 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d DELETE.** statem
130c0 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 ent within the b
130d0 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 ody of the same
130e0 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 trigger..** Howe
130f0 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 ver, the number
13100 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f returned does no
13110 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 t include change
13120 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 s.** caused by s
13130 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 ubtriggers since
13140 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 those have thei
13150 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e r own context.)^
13160 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 .**.** See also
13170 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 the [sqlite3_tot
13180 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e al_changes()] in
13190 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 terface, the.**
131a0 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 [count_changes p
131b0 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 ragma], and the
131c0 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 [changes() SQL f
131d0 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 unction]..**.**
131e0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 If a separate th
131f0 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 read makes chang
13200 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 es on the same d
13210 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
13220 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c on.** while [sql
13230 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 ite3_changes()]
13240 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 is running then
13250 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
13260 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 ed.** is unpredi
13270 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d ctable and not m
13280 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 eaningful..*/.SQ
13290 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
132a0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c ite3_changes(sql
132b0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ite3*);../*.** C
132c0 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e API3REF: Total N
132d0 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f umber Of Rows Mo
132e0 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 dified.**.** ^Th
132f0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 is function retu
13300 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
13310 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 f row changes ca
13320 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d used by [INSERT]
13330 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 ,.** [UPDATE] or
13340 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d [DELETE] statem
13350 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b ents since the [
13360 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
13370 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e ion] was opened.
13380 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 .** ^(The count
13390 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
133a0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 te3_total_change
133b0 73 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c s() includes all
133c0 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d changes.** from
133d0 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49 all [CREATE TRI
133e0 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20 GGER | trigger]
133f0 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61 contexts and cha
13400 6e 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 nges made by.**
13410 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 [foreign key act
13420 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a ions]. However,.
13430 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 ** the count doe
13440 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 s not include ch
13450 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d anges used to im
13460 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 plement [REPLACE
13470 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a ] constraints,.*
13480 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f * do rollbacks o
13490 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 r ABORT processi
134a0 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 ng, or [DROP TAB
134b0 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 LE] processing.
134c0 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f The.** count do
134d0 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 es not include r
134e0 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74 68 61 ows of views tha
134f0 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 t fire an [INSTE
13500 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a AD OF trigger],.
13510 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68 65 ** though if the
13520 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 INSTEAD OF trig
13530 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 ger makes change
13540 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 s of its own, th
13550 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 ose changes .**
13560 61 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a are counted.)^.*
13570 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 * ^The sqlite3_t
13580 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 otal_changes() f
13590 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 unction counts t
135a0 68 65 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f he changes as so
135b0 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 on as.** the sta
135c0 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 tement that make
135d0 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 s them is comple
135e0 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 ted (when the st
135f0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a atement handle.*
13600 2a 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b * is passed to [
13610 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
13620 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e or [sqlite3_fin
13630 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a alize()])..**.**
13640 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 See also the [s
13650 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 qlite3_changes()
13660 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 ] interface, the
13670 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 .** [count_chang
13680 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 es pragma], and
13690 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 the [total_chang
136a0 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f es() SQL functio
136b0 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 n]..**.** If a s
136c0 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d eparate thread m
136d0 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 akes changes on
136e0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
136f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
13700 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 while [sqlite3_t
13710 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 otal_changes()]
13720 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 is running then
13730 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 the value.** ret
13740 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 urned is unpredi
13750 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d ctable and not m
13760 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 eaningful..*/.SQ
13770 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
13780 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
13790 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f es(sqlite3*);../
137a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 *.** CAPI3REF: I
137b0 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d nterrupt A Long-
137c0 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a Running Query.**
137d0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 .** ^This functi
137e0 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 on causes any pe
137f0 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f nding database o
13800 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 peration to abor
13810 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 t and.** return
13820 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 at its earliest
13830 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 opportunity. Thi
13840 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 s routine is typ
13850 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 ically.** called
13860 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 in response to
13870 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 a user action su
13880 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 ch as pressing "
13890 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 Cancel".** or Ct
138a0 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 rl-C where the u
138b0 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 ser wants a long
138c0 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e query operation
138d0 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 to halt.** imme
138e0 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e diately..**.** ^
138f0 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 It is safe to ca
13900 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 ll this routine
13910 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 from a thread di
13920 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 fferent from the
13930 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 .** thread that
13940 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e is currently run
13950 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 ning the databas
13960 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 e operation. Bu
13970 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 t it.** is not s
13980 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 afe to call this
13990 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 routine with a
139a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
139b0 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 tion] that.** is
139c0 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 closed or might
139d0 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 close before sq
139e0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
139f0 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a ) returns..**.**
13a00 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 ^If an SQL oper
13a10 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 ation is very ne
13a20 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 arly finished at
13a30 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a the time when.*
13a40 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 * sqlite3_interr
13a50 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c upt() is called,
13a60 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e then it might n
13a70 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 ot have an oppor
13a80 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 tunity.** to be
13a90 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 interrupted and
13aa0 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 might continue t
13ab0 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a o completion..**
13ac0 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 .** ^An SQL oper
13ad0 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e ation that is in
13ae0 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 terrupted will r
13af0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e eturn [SQLITE_IN
13b00 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 TERRUPT]..** ^If
13b10 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 the interrupted
13b20 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 SQL operation i
13b30 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 s an INSERT, UPD
13b40 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a ATE, or DELETE.*
13b50 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 * that is inside
13b60 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 an explicit tra
13b70 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 nsaction, then t
13b80 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 he entire transa
13b90 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 ction.** will be
13ba0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 rolled back aut
13bb0 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a omatically..**.*
13bc0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 * ^The sqlite3_i
13bd0 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c nterrupt(D) call
13be0 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e is in effect un
13bf0 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c til all currentl
13c00 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c y running.** SQL
13c10 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b statements on [
13c20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
13c30 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e ion] D complete.
13c40 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 ^Any new SQL s
13c50 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 tatements.** tha
13c60 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 t are started af
13c70 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f ter the sqlite3_
13c80 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c interrupt() call
13c90 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 and before the
13ca0 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 .** running stat
13cb0 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a ements reaches z
13cc0 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 ero are interrup
13cd0 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 ted as if they h
13ce0 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 ad been.** runni
13cf0 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 ng prior to the
13d00 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
13d10 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 t() call. ^New
13d20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a SQL statements.*
13d30 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 * that are start
13d40 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e ed after the run
13d50 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 ning statement c
13d60 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 ount reaches zer
13d70 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 o are.** not eff
13d80 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c ected by the sql
13d90 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
13da0 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 ..** ^A call to
13db0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
13dc0 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 t(D) that occurs
13dd0 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 when there are
13de0 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 no running.** SQ
13df0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 L statements is
13e00 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 a no-op and has
13e10 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c no effect on SQL
13e20 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 statements.** t
13e30 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 hat are started
13e40 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 after the sqlite
13e50 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 3_interrupt() ca
13e60 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a ll returns..**.*
13e70 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 * If the databas
13e80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f e connection clo
13e90 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 ses while [sqlit
13ea0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a e3_interrupt()].
13eb0 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 ** is running th
13ec0 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 en bad things wi
13ed0 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e ll likely happen
13ee0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
13ef0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 void sqlite3_int
13f00 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 errupt(sqlite3*)
13f10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
13f20 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 F: Determine If
13f30 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 An SQL Statement
13f40 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a Is Complete.**.
13f50 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
13f60 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 s are useful dur
13f70 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 ing command-line
13f80 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d input to determ
13f90 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 ine if the.** cu
13fa0 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 rrently entered
13fb0 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f text seems to fo
13fc0 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 rm a complete SQ
13fd0 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a L statement or.*
13fe0 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 * if additional
13ff0 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 input is needed
14000 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 before sending t
14010 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 he text into.**
14020 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 SQLite for parsi
14030 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 ng. ^These rout
14040 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 ines return 1 if
14050 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e the input strin
14060 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 g.** appears to
14070 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 be a complete SQ
14080 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 L statement. ^A
14090 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 statement is ju
140a0 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f dged to be.** co
140b0 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 mplete if it end
140c0 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c s with a semicol
140d0 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 on token and is
140e0 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 not a prefix of
140f0 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 a.** well-formed
14100 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 CREATE TRIGGER
14110 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d statement. ^Sem
14120 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 icolons that are
14130 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e embedded within
14140 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 .** string liter
14150 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 als or quoted id
14160 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f entifier names o
14170 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e r comments are n
14180 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e ot.** independen
14190 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 t tokens (they a
141a0 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 re part of the t
141b0 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 oken in which th
141c0 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 ey are.** embedd
141d0 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 ed) and thus do
141e0 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 not count as a s
141f0 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 tatement termina
14200 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 tor. ^Whitespac
14210 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 e.** and comment
14220 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 s that follow th
14230 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f e final semicolo
14240 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a n are ignored..*
14250 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 *.** ^These rout
14260 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 ines return 0 if
14270 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 the statement i
14280 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e s incomplete. ^
14290 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 If a.** memory a
142a0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c llocation fails,
142b0 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d then SQLITE_NOM
142c0 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a EM is returned..
142d0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 **.** ^These rou
142e0 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 tines do not par
142f0 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 se the SQL state
14300 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 ments thus.** wi
14310 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 ll not detect sy
14320 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f ntactically inco
14330 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a rrect SQL..**.**
14340 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 ^(If SQLite has
14350 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 not been initia
14360 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c lized using [sql
14370 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
14380 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 )] prior .** to
14390 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 invoking sqlite3
143a0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 _complete16() th
143b0 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 en sqlite3_initi
143c0 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b alize() is invok
143d0 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 ed.** automatica
143e0 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 lly by sqlite3_c
143f0 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 omplete16(). If
14400 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 that initializa
14410 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 tion fails,.** t
14420 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 hen the return v
14430 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 alue from sqlite
14440 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 3_complete16() w
14450 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a ill be non-zero.
14460 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 ** regardless of
14470 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
14480 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 the input SQL is
14490 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a complete.)^.**.
144a0 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 ** The input to
144b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 [sqlite3_complet
144c0 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a e()] must be a z
144d0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a ero-terminated.*
144e0 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a * UTF-8 string..
144f0 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 **.** The input
14500 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 to [sqlite3_comp
14510 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 lete16()] must b
14520 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 e a zero-termina
14530 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 ted.** UTF-16 st
14540 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 ring in native b
14550 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 yte order..*/.SQ
14560 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
14570 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f ite3_complete(co
14580 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a nst char *sql);.
14590 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
145a0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 qlite3_complete1
145b0 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6(const void *sq
145c0 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 l);../*.** CAPI3
145d0 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 REF: Register A
145e0 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 Callback To Hand
145f0 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 le SQLITE_BUSY E
14600 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 rrors.**.** ^Thi
14610 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 s routine sets a
14620 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
14630 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 on that might be
14640 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 invoked wheneve
14650 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 r.** an attempt
14660 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 is made to open
14670 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 a database table
14680 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 that another th
14690 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 read.** or proce
146a0 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a ss has locked..*
146b0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 *.** ^If the bus
146c0 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 y callback is NU
146d0 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 LL, then [SQLITE
146e0 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 _BUSY] or [SQLIT
146f0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d E_IOERR_BLOCKED]
14700 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 .** is returned
14710 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e immediately upon
14720 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 encountering th
14730 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 e lock. ^If the
14740 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a busy callback.*
14750 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 * is not NULL, t
14760 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b hen the callback
14770 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 might be invoke
14780 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d d with two argum
14790 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ents..**.** ^The
147a0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
147b0 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 to the busy hand
147c0 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 ler is a copy of
147d0 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 the void* point
147e0 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 er which.** is t
147f0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e he third argumen
14800 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 t to sqlite3_bus
14810 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 y_handler(). ^T
14820 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
14830 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 nt to.** the bus
14840 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 y handler callba
14850 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 ck is the number
14860 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 of times that t
14870 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 he busy handler
14880 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f has.** been invo
14890 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 ked for this loc
148a0 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 king event. ^If
148b0 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c the.** busy cal
148c0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c lback returns 0,
148d0 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f then no additio
148e0 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 nal attempts are
148f0 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 made to.** acce
14900 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ss the database
14910 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 and [SQLITE_BUSY
14920 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 ] or [SQLITE_IOE
14930 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 RR_BLOCKED] is r
14940 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 eturned..** ^If
14950 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 the callback ret
14960 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 urns non-zero, t
14970 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 hen another atte
14980 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 mpt.** is made t
14990 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 o open the datab
149a0 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 ase for reading
149b0 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 and the cycle re
149c0 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 peats..**.** The
149d0 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 presence of a b
149e0 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 usy handler does
149f0 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 not guarantee t
14a00 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 hat it will be i
14a10 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 nvoked.** when t
14a20 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e here is lock con
14a30 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c tention. ^If SQL
14a40 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 ite determines t
14a50 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 hat invoking the
14a60 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 busy.** handler
14a70 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e could result in
14a80 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 a deadlock, it
14a90 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e will go ahead an
14aa0 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 d return [SQLITE
14ab0 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 _BUSY].** or [SQ
14ac0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b LITE_IOERR_BLOCK
14ad0 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 ED] instead of i
14ae0 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 nvoking the busy
14af0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e handler..** Con
14b00 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f sider a scenario
14b10 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 where one proce
14b20 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 ss is holding a
14b30 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a read lock that.*
14b40 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 * it is trying t
14b50 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 o promote to a r
14b60 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 eserved lock and
14b70 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f .** a second pro
14b80 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 cess is holding
14b90 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 a reserved lock
14ba0 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e that it is tryin
14bb0 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 g.** to promote
14bc0 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 to an exclusive
14bd0 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 lock. The first
14be0 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 process cannot
14bf0 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 proceed.** becau
14c00 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 se it is blocked
14c10 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 by the second a
14c20 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 nd the second pr
14c30 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 ocess cannot.**
14c40 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 proceed because
14c50 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 it is blocked by
14c60 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 the first. If
14c70 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a both processes.*
14c80 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 * invoke the bus
14c90 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 y handlers, neit
14ca0 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e her will make an
14cb0 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 y progress. The
14cc0 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 refore,.** SQLit
14cd0 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 e returns [SQLIT
14ce0 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 E_BUSY] for the
14cf0 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 first process, h
14d00 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a oping that this.
14d10 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 ** will induce t
14d20 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 he first process
14d30 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 to release its
14d40 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c read lock and al
14d50 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e low.** the secon
14d60 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f d process to pro
14d70 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ceed..**.** ^The
14d80 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 default busy ca
14d90 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a llback is NULL..
14da0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 **.** ^The [SQLI
14db0 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 TE_BUSY] error i
14dc0 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b s converted to [
14dd0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f SQLITE_IOERR_BLO
14de0 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 CKED].** when SQ
14df0 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d Lite is in the m
14e00 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 iddle of a large
14e10 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 transaction whe
14e20 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 re all the.** ch
14e30 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 anges will not f
14e40 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d it into the in-m
14e50 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 emory cache. SQ
14e60 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 Lite will.** alr
14e70 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 eady hold a RESE
14e80 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 RVED lock on the
14e90 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 database file,
14ea0 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 but it needs.**
14eb0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 to promote this
14ec0 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 lock to EXCLUSIV
14ed0 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e E so that it can
14ee0 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 spill cache.**
14ef0 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 pages into the d
14f00 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 atabase file wit
14f10 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e hout harm to con
14f20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 current.** reade
14f30 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75 rs. ^If it is u
14f40 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 nable to promote
14f50 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 the lock, then
14f60 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a the in-memory.**
14f70 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c cache will be l
14f80 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 eft in an incons
14f90 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 istent state and
14fa0 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a so the error.**
14fb0 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 code is promote
14fc0 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 d from the relat
14fd0 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 ively benign [SQ
14fe0 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a LITE_BUSY] to.**
14ff0 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 the more severe
15000 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 [SQLITE_IOERR_B
15010 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 LOCKED]. ^This
15020 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f error code promo
15030 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 tion.** forces a
15040 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c n automatic roll
15050 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e back of the chan
15060 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a ges. See the.**
15070 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 <a href="/cvstr
15080 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 ac/wiki?p=Corrup
15090 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 tionFollowingBus
150a0 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 yError">.** Corr
150b0 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 uptionFollowingB
150c0 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b usyError</a> wik
150d0 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 i page for a dis
150e0 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a cussion of why.*
150f0 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 * this is import
15100 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 ant..**.** ^(The
15110 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 re can only be a
15120 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e single busy han
15130 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 dler defined for
15140 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 each.** [databa
15150 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 se connection].
15160 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 Setting a new b
15170 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 usy handler clea
15180 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f rs any.** previo
15190 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 usly set handler
151a0 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 .)^ ^Note that
151b0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 calling [sqlite3
151c0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d _busy_timeout()]
151d0 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 .** will also se
151e0 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62 t or clear the b
151f0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a usy handler..**.
15200 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c ** The busy call
15210 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 back should not
15220 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 take any actions
15230 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 which modify th
15240 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f e.** database co
15250 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e nnection that in
15260 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 voked the busy h
15270 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 andler. Any suc
15280 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 h actions.** res
15290 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 ult in undefined
152a0 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a behavior..** .*
152b0 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 * A busy handler
152c0 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 must not close
152d0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
152e0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 nection.** or [p
152f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
15300 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 t] that invoked
15310 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
15320 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
15330 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 int sqlite3_busy
15340 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 _handler(sqlite3
15350 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c *, int(*)(void*,
15360 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f int), void*);../
15370 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
15380 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 et A Busy Timeou
15390 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f t.**.** ^This ro
153a0 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 utine sets a [sq
153b0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c lite3_busy_handl
153c0 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 er | busy handle
153d0 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a r] that sleeps.*
153e0 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 * for a specifie
153f0 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 d amount of time
15400 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 when a table is
15410 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 locked. ^The h
15420 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 andler.** will s
15430 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 leep multiple ti
15440 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 mes until at lea
15450 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 st "ms" millisec
15460 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 onds of sleeping
15470 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c .** have accumul
15480 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 ated. ^After at
15490 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c least "ms" mill
154a0 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 iseconds of slee
154b0 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e ping,.** the han
154c0 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 dler returns 0 w
154d0 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c hich causes [sql
154e0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 ite3_step()] to
154f0 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 return.** [SQLIT
15500 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 E_BUSY] or [SQLI
15510 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 TE_IOERR_BLOCKED
15520 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e ]..**.** ^Callin
15530 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 g this routine w
15540 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 ith an argument
15550 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 less than or equ
15560 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 al to zero.** tu
15570 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 rns off all busy
15580 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a handlers..**.**
15590 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c ^(There can onl
155a0 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 y be a single bu
155b0 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 sy handler for a
155c0 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b particular.** [
155d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
155e0 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 ion] any any giv
155f0 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 en moment. If a
15600 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 nother busy hand
15610 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e ler.** was defin
15620 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 ed (using [sqli
15630 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 te3_busy_handler
15640 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 ()]) prior to ca
15650 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f lling.** this ro
15660 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 utine, that othe
15670 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 r busy handler i
15680 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a s cleared.)^.*/.
15690 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
156a0 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 qlite3_busy_time
156b0 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e out(sqlite3*, in
156c0 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 t ms);../*.** CA
156d0 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 PI3REF: Convenie
156e0 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 nce Routines For
156f0 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 Running Queries
15700 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 .**.** This is a
15710 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 legacy interfac
15720 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72 e that is preser
15730 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 ved for backward
15740 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e s compatibility.
15750 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 .** Use of this
15760 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 interface is not
15770 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a recommended..**
15780 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 .** Definition:
15790 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c A <b>result tabl
157a0 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 e</b> is memory
157b0 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 data structure c
157c0 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a reated by the.**
157d0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 [sqlite3_get_ta
157e0 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ble()] interface
157f0 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c . A result tabl
15800 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a e records the.**
15810 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 complete query
15820 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 results from one
15830 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 or more queries
15840 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c ..**.** The tabl
15850 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 e conceptually h
15860 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 as a number of r
15870 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e ows and columns.
15880 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e But.** these n
15890 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 umbers are not p
158a0 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c art of the resul
158b0 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 t table itself.
158c0 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 These.** number
158d0 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 s are obtained s
158e0 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 eparately. Let
158f0 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 N be the number
15900 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d of rows.** and M
15910 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f be the number o
15920 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a f columns..**.**
15930 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 A result table
15940 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 is an array of p
15950 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d ointers to zero-
15960 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 terminated UTF-8
15970 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 strings..** The
15980 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 re are (N+1)*M e
15990 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 lements in the a
159a0 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 rray. The first
159b0 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e M pointers poin
159c0 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 t.** to zero-ter
159d0 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 minated strings
159e0 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 that contain th
159f0 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 e names of the c
15a00 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 olumns..** The r
15a10 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 emaining entries
15a20 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 all point to qu
15a30 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 ery results. NU
15a40 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 LL values result
15a50 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e .** in NULL poin
15a60 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 ters. All other
15a70 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 values are in t
15a80 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d heir UTF-8 zero-
15a90 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 terminated.** st
15aa0 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 ring representat
15ab0 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 ion as returned
15ac0 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by [sqlite3_colu
15ad0 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a mn_text()]..**.*
15ae0 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 * A result table
15af0 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f might consist o
15b00 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 f one or more me
15b10 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 mory allocations
15b20 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 ..** It is not s
15b30 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 afe to pass a re
15b40 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 sult table direc
15b50 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f tly to [sqlite3_
15b60 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 free()]..** A re
15b70 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c sult table shoul
15b80 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 d be deallocated
15b90 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
15ba0 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a free_table()]..*
15bb0 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 *.** ^(As an exa
15bc0 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 mple of the resu
15bd0 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c lt table format,
15be0 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 suppose a query
15bf0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 result.** is as
15c00 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 follows:.**.**
15c10 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
15c20 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 >.** Name
15c30 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a | Age.**
15c40 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d --------
15c50 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a ---------------.
15c60 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 ** Alice
15c70 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 | 43.**
15c80 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 Bob
15c90 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 | 28.**
15ca0 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 Cindy | 21
15cb0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
15cc0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 kquote>.**.** Th
15cd0 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 ere are two colu
15ce0 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 mn (M==2) and th
15cf0 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e ree rows (N==3).
15d00 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 Thus the.** re
15d10 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 sult table has 8
15d20 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f entries. Suppo
15d30 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 se the result ta
15d40 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a ble is stored.**
15d50 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d in an array nam
15d60 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 es azResult. Th
15d70 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 en azResult hold
15d80 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a s this content:.
15d90 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
15da0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 e><pre>.**
15db0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 azResult[0
15dc0 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 ] = "Name";.**
15dd0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
15de0 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 91;1] = "Age";.*
15df0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
15e00 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 t[2] = "Alic
15e10 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a e";.** az
15e20 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 Result[3] =
15e30 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 "43";.**
15e40 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 azResult[4]
15e50 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 = "Bob";.**
15e60 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
15e70 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 5] = "28";.**
15e80 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
15e90 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 1;6] = "Cindy";.
15ea0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
15eb0 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 lt[7] = "21"
15ec0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f ;.** </pre></blo
15ed0 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a ckquote>)^.**.**
15ee0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 ^The sqlite3_ge
15ef0 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 t_table() functi
15f00 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 on evaluates one
15f10 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 or more.** semi
15f20 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 colon-separated
15f30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 SQL statements i
15f40 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 n the zero-termi
15f50 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 nated UTF-8.** s
15f60 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 tring of its 2nd
15f70 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 parameter and r
15f80 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 eturns a result
15f90 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 table to the.**
15fa0 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e pointer given in
15fb0 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 its 3rd paramet
15fc0 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 er..**.** After
15fd0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
15fe0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 has finished wit
15ff0 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f h the result fro
16000 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 m sqlite3_get_ta
16010 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 ble(),.** it mus
16020 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c t pass the resul
16030 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 t table pointer
16040 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f to sqlite3_free_
16050 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 table() in order
16060 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 to.** release t
16070 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 he memory that w
16080 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 as malloced. Be
16090 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 cause of the way
160a0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
160b0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 _malloc()] happe
160c0 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 ns within sqlite
160d0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 3_get_table(), t
160e0 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 he calling.** fu
160f0 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 nction must not
16100 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c try to call [sql
16110 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 ite3_free()] dir
16120 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 ectly. Only.**
16130 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 [sqlite3_free_ta
16140 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 ble()] is able t
16150 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 o release the me
16160 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e mory properly an
16170 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 d safely..**.**
16180 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f The sqlite3_get_
16190 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 table() interfac
161a0 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 e is implemented
161b0 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 as a wrapper ar
161c0 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ound.** [sqlite3
161d0 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 _exec()]. The s
161e0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 qlite3_get_table
161f0 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 () routine does
16200 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a not have access.
16210 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e ** to any intern
16220 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 al data structur
16230 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 es of SQLite. I
16240 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 t uses only the
16250 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 public.** interf
16260 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 ace defined here
16270 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 . As a conseque
16280 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 nce, errors that
16290 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a occur in the.**
162a0 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f wrapper layer o
162b0 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e utside of the in
162c0 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f ternal [sqlite3_
162d0 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 exec()] call are
162e0 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 not.** reflecte
162f0 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 d in subsequent
16300 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
16310 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 3_errcode()] or.
16320 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d ** [sqlite3_errm
16330 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 sg()]..*/.SQLITE
16340 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
16350 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 _get_table(. sq
16360 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
16370 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 /* An open d
16380 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e atabase */. con
16390 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 st char *zSql,
163a0 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 /* SQL to be
163b0 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 evaluated */. c
163c0 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 har ***pazResult
163d0 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 , /* Results
163e0 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a of the query */.
163f0 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 int *pnRow,
16400 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 /* Numbe
16410 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 r of result rows
16420 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f written here */
16430 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e . int *pnColumn
16440 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 , /* Numb
16450 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c er of result col
16460 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 umns written her
16470 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a e */. char **pz
16480 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 Errmsg /*
16490 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 Error msg writte
164a0 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c n here */.);.SQL
164b0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c ITE_API void sql
164c0 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 ite3_free_table(
164d0 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a char **result);.
164e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
164f0 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e Formatted Strin
16500 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 g Printing Funct
16510 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ions.**.** These
16520 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f routines are wo
16530 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 rk-alikes of the
16540 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 "printf()" fami
16550 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a ly of functions.
16560 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e ** from the stan
16570 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a dard C library..
16580 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
16590 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 e3_mprintf() and
165a0 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 sqlite3_vmprint
165b0 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 f() routines wri
165c0 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 te their.** resu
165d0 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 lts into memory
165e0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 obtained from [s
165f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
16600 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 ..** The strings
16610 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 returned by the
16620 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 se two routines
16630 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c should be.** rel
16640 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 eased by [sqlite
16650 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 3_free()]. ^Bot
16660 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 h routines retur
16670 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e n a.** NULL poin
16680 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f ter if [sqlite3_
16690 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 malloc()] is una
166a0 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 ble to allocate
166b0 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 enough.** memory
166c0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 to hold the res
166d0 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a ulting string..*
166e0 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 *.** ^(The sqlit
166f0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f e3_snprintf() ro
16700 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 utine is similar
16710 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 to "snprintf()"
16720 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 from.** the sta
16730 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e ndard C library.
16740 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 The result is
16750 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 written into the
16760 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c .** buffer suppl
16770 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e ied as the secon
16780 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 d parameter whos
16790 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 e size is given
167a0 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 by.** the first
167b0 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 parameter. Note
167c0 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f that the order o
167d0 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 f the.** first t
167e0 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 wo parameters is
167f0 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 reversed from s
16800 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 nprintf().)^ Th
16810 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 is is an.** hist
16820 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 orical accident
16830 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 that cannot be f
16840 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 ixed without bre
16850 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 aking.** backwar
16860 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ds compatibility
16870 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 . ^(Note also t
16880 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 hat sqlite3_snpr
16890 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e intf().** return
168a0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 s a pointer to i
168b0 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 ts buffer instea
168c0 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 d of the number
168d0 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 of.** characters
168e0 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 actually writte
168f0 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 n into the buffe
16900 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 r.)^ We admit t
16910 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 hat.** the numbe
16920 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 r of characters
16930 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 written would be
16940 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 a more useful r
16950 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 eturn.** value b
16960 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 ut we cannot cha
16970 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e nge the implemen
16980 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 tation of sqlite
16990 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 3_snprintf().**
169a0 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 now without brea
169b0 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 king compatibili
169c0 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f ty..**.** ^As lo
169d0 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 ng as the buffer
169e0 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 size is greater
169f0 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 than zero, sqli
16a00 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a te3_snprintf().*
16a10 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 * guarantees tha
16a20 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 t the buffer is
16a30 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d always zero-term
16a40 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 inated. ^The fi
16a50 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 rst.** parameter
16a60 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 "n" is the tota
16a70 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 l size of the bu
16a80 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 ffer, including
16a90 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 space for.** the
16aa0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 zero terminator
16ab0 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 . So the longes
16ac0 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 t string that ca
16ad0 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a n be completely.
16ae0 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 ** written will
16af0 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 be n-1 character
16b00 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 s..**.** ^The sq
16b10 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 lite3_vsnprintf(
16b20 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 ) routine is a v
16b30 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f arargs version o
16b40 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e f sqlite3_snprin
16b50 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 tf()..**.** Thes
16b60 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 e routines all i
16b70 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 mplement some ad
16b80 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 ditional formatt
16b90 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 ing.** options t
16ba0 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 hat are useful f
16bb0 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 or constructing
16bc0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a SQL statements..
16bd0 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 ** All of the us
16be0 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 ual printf() for
16bf0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 matting options
16c00 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 apply. In addit
16c10 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 ion, there.** is
16c20 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c are "%q", "%Q",
16c30 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e and "%z" option
16c40 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 s..**.** ^(The %
16c50 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c q option works l
16c60 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 ike %s in that i
16c70 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 t substitutes a
16c80 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a null-terminated.
16c90 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 ** string from t
16ca0 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 he argument list
16cb0 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 . But %q also d
16cc0 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 oubles every '\'
16cd0 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 ' character..**
16ce0 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 %q is designed f
16cf0 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 or use inside a
16d00 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 string literal.)
16d10 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 ^ By doubling e
16d20 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 ach '\''.** char
16d30 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73 acter it escapes
16d40 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20 that character
16d50 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f and allows it to
16d60 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 be inserted int
16d70 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e o.** the string.
16d80 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 .**.** For examp
16d90 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 le, assume the s
16da0 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a tring variable z
16db0 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 Text contains te
16dc0 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a xt as follows:.*
16dd0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
16de0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 ><pre>.** char
16df0 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 *zText = "It's a
16e00 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a happy day!";.**
16e10 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 </pre></blockqu
16e20 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 ote>.**.** One c
16e30 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74 an use this text
16e40 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 in an SQL state
16e50 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a ment as follows:
16e60 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
16e70 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 te><pre>.** cha
16e80 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 r *zSQL = sqlite
16e90 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 3_mprintf("INSER
16ea0 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c T INTO table VAL
16eb0 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 UES('%q')", zTex
16ec0 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f t);.** sqlite3_
16ed0 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 exec(db, zSQL, 0
16ee0 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c , 0, 0);.** sql
16ef0 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b ite3_free(zSQL);
16f00 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
16f10 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 kquote>.**.** Be
16f20 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 cause the %q for
16f30 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 mat string is us
16f40 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 ed, the '\'' cha
16f50 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a racter in zText.
16f60 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e ** is escaped an
16f70 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 d the SQL genera
16f80 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 ted is as follow
16f90 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 s:.**.** <blockq
16fa0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 uote><pre>.** I
16fb0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 NSERT INTO table
16fc0 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 1 VALUES('It''s
16fd0 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a a happy day!').*
16fe0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
16ff0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 uote>.**.** This
17000 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 is correct. Ha
17010 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 d we used %s ins
17020 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 tead of %q, the
17030 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a generated SQL.**
17040 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b would have look
17050 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a ed like this:.**
17060 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
17070 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 <pre>.** INSERT
17080 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c INTO table1 VAL
17090 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70 UES('It's a happ
170a0 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 y day!');.** </p
170b0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
170c0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f .**.** This seco
170d0 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e nd example is an
170e0 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f SQL syntax erro
170f0 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c r. As a general
17100 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 rule you should
17110 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 .** always use %
17120 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 q instead of %s
17130 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 when inserting t
17140 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e ext into a strin
17150 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a g literal..**.**
17160 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e ^(The %Q option
17170 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 works like %q e
17180 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 xcept it also ad
17190 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 ds single quotes
171a0 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f around.** the o
171b0 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f utside of the to
171c0 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 tal string. Add
171d0 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 itionally, if th
171e0 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 e parameter in t
171f0 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c he.** argument l
17200 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f ist is a NULL po
17210 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 inter, %Q substi
17220 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22 tutes the text "
17230 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a NULL" (without.*
17240 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 * single quotes)
17250 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 .)^ So, for exa
17260 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 mple, one could
17270 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 say:.**.** <bloc
17280 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 kquote><pre>.**
17290 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 char *zSQL = sq
172a0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 lite3_mprintf("I
172b0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 NSERT INTO table
172c0 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 VALUES(%Q)", zT
172d0 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 ext);.** sqlite
172e0 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 3_exec(db, zSQL,
172f0 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 0, 0, 0);.** s
17300 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c qlite3_free(zSQL
17310 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c );.** </pre></bl
17320 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
17330 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 The code above w
17340 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 ill render a cor
17350 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 rect SQL stateme
17360 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a nt in the zSQL.*
17370 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 * variable even
17380 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 if the zText var
17390 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 iable is a NULL
173a0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e pointer..**.** ^
173b0 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 (The "%z" format
173c0 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b ting option work
173d0 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 s like "%s" but
173e0 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 with the.** addi
173f0 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 tion that after
17400 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 the string has b
17410 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 een read and cop
17420 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 ied into.** the
17430 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 result, [sqlite3
17440 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c _free()] is call
17450 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 ed on the input
17460 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c string.)^.*/.SQL
17470 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 ITE_API char *sq
17480 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f lite3_mprintf(co
17490 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a nst char*,...);.
174a0 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 SQLITE_API char
174b0 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 *sqlite3_vmprint
174c0 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 f(const char*, v
174d0 61 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f a_list);.SQLITE_
174e0 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 API char *sqlite
174f0 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 3_snprintf(int,c
17500 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a har*,const char*
17510 2c 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 , ...);.SQLITE_A
17520 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 PI char *sqlite3
17530 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 _vsnprintf(int,c
17540 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a har*,const char*
17550 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a , va_list);../*.
17560 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d ** CAPI3REF: Mem
17570 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 ory Allocation S
17580 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 ubsystem.**.** T
17590 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 he SQLite core u
175a0 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20 ses these three
175b0 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c routines for all
175c0 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 of its own.** i
175d0 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 nternal memory a
175e0 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e llocation needs.
175f0 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 "Core" in the p
17600 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 revious sentence
17610 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 .** does not inc
17620 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 lude operating-s
17630 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 ystem specific V
17640 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f FS implementatio
17650 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f n. The.** Windo
17660 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 ws VFS uses nati
17670 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 ve malloc() and
17680 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 free() for some
17690 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a operations..**.*
176a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d * ^The sqlite3_m
176b0 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 alloc() routine
176c0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
176d0 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 r to a block.**
176e0 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 of memory at lea
176f0 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 st N bytes in le
17700 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 ngth, where N is
17710 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a the parameter..
17720 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d ** ^If sqlite3_m
17730 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c alloc() is unabl
17740 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 e to obtain suff
17750 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d icient free.** m
17760 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e emory, it return
17770 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
17780 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d . ^If the param
17790 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c eter N to.** sql
177a0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 ite3_malloc() is
177b0 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 zero or negativ
177c0 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d e then sqlite3_m
177d0 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a alloc() returns.
177e0 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ** a NULL pointe
177f0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e r..**.** ^Callin
17800 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 g sqlite3_free()
17810 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 with a pointer
17820 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 previously retur
17830 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 ned.** by sqlite
17840 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 3_malloc() or sq
17850 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 lite3_realloc()
17860 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 releases that me
17870 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 mory so.** that
17880 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 it might be reus
17890 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 ed. ^The sqlite
178a0 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 3_free() routine
178b0 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 is.** a no-op i
178c0 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 f is called with
178d0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
178e0 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c Passing a NULL
178f0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 pointer.** to s
17900 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 qlite3_free() is
17910 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 harmless. Afte
17920 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d r being freed, m
17930 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 emory.** should
17940 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 neither be read
17950 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 nor written. Ev
17960 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 en reading previ
17970 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d ously freed.** m
17980 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 emory might resu
17990 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 lt in a segmenta
179a0 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 tion fault or ot
179b0 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 her severe error
179c0 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 ..** Memory corr
179d0 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e uption, a segmen
179e0 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 tation fault, or
179f0 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 other severe er
17a00 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 ror.** might res
17a10 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 ult if sqlite3_f
17a20 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 ree() is called
17a30 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 with a non-NULL
17a40 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 pointer that.**
17a50 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 was not obtained
17a60 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 from sqlite3_ma
17a70 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 lloc() or sqlite
17a80 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 3_realloc()..**.
17a90 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 ** ^(The sqlite3
17aa0 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 _realloc() inter
17ab0 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f face attempts to
17ac0 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 resize a.** pri
17ad0 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 or memory alloca
17ae0 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 tion to be at le
17af0 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 ast N bytes, whe
17b00 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 re N is the.** s
17b10 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e econd parameter.
17b20 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c The memory all
17b30 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 ocation to be re
17b40 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 sized is the fir
17b50 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e st.** parameter.
17b60 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72 73 )^ ^ If the firs
17b70 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 t parameter to s
17b80 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
17b90 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f .** is a NULL po
17ba0 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 inter then its b
17bb0 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 ehavior is ident
17bc0 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a ical to calling.
17bd0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f ** sqlite3_mallo
17be0 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 c(N) where N is
17bf0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
17c00 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
17c10 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 realloc()..** ^I
17c20 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 f the second par
17c30 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
17c40 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 3_realloc() is z
17c50 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 ero or.** negati
17c60 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 ve then the beha
17c70 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 vior is exactly
17c80 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c the same as call
17c90 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 ing.** sqlite3_f
17ca0 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69 ree(P) where P i
17cb0 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 s the first para
17cc0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
17cd0 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e _realloc()..** ^
17ce0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
17cf0 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e ) returns a poin
17d00 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 ter to a memory
17d10 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 allocation.** of
17d20 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 at least N byte
17d30 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c s in size or NUL
17d40 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 L if sufficient
17d50 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 memory is unavai
17d60 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 lable..** ^If M
17d70 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 is the size of t
17d80 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 he prior allocat
17d90 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c ion, then min(N,
17da0 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 M) bytes.** of t
17db0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 he prior allocat
17dc0 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 ion are copied i
17dd0 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e nto the beginnin
17de0 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 g of buffer retu
17df0 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 rned.** by sqlit
17e00 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 e3_realloc() and
17e10 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 the prior alloc
17e20 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a ation is freed..
17e30 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 ** ^If sqlite3_r
17e40 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 ealloc() returns
17e50 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 NULL, then the
17e60 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e prior allocation
17e70 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 .** is not freed
17e80 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d ..**.** ^The mem
17e90 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 ory returned by
17ea0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
17eb0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 and sqlite3_rea
17ec0 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 lloc().** is alw
17ed0 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 ays aligned to a
17ee0 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 t least an 8 byt
17ef0 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 e boundary, or t
17f00 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f o a.** 4 byte bo
17f10 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 undary if the [S
17f20 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 QLITE_4_BYTE_ALI
17f30 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d GNED_MALLOC] com
17f40 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 pile-time.** opt
17f50 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a ion is used..**.
17f60 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 ** In SQLite ver
17f70 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 sion 3.5.0 and 3
17f80 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 .5.1, it was pos
17f90 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a sible to define.
17fa0 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d ** the SQLITE_OM
17fb0 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 IT_MEMORY_ALLOCA
17fc0 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 TION which would
17fd0 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 cause the built
17fe0 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 -in.** implement
17ff0 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 ation of these r
18000 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d outines to be om
18010 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 itted. That cap
18020 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f ability.** is no
18030 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 longer provided
18040 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e . Only built-in
18050 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
18060 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a rs can be used..
18070 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 **.** The Window
18080 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c s OS interface l
18090 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 ayer calls.** th
180a0 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 e system malloc(
180b0 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 ) and free() dir
180c0 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 ectly when conve
180d0 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d rting.** filenam
180e0 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 es between the U
180f0 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 TF-8 encoding us
18100 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 ed by SQLite.**
18110 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c and whatever fil
18120 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 ename encoding i
18130 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 s used by the pa
18140 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 rticular Windows
18150 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e .** installation
18160 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 . Memory alloca
18170 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20 tion errors are
18180 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a detected, but.**
18190 20 74 68 65 79 20 61 72 65 20 72 65 70 6f 72 74 they are report
181a0 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 ed back as [SQLI
181b0 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a TE_CANTOPEN] or.
181c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 ** [SQLITE_IOERR
181d0 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 ] rather than [S
181e0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a QLITE_NOMEM]..**
181f0 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 .** The pointer
18200 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 arguments to [sq
18210 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e lite3_free()] an
18220 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c d [sqlite3_reall
18230 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 oc()].** must be
18240 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 either NULL or
18250 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 else pointers ob
18260 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 tained from a pr
18270 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f ior.** invocatio
18280 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 n of [sqlite3_ma
18290 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 lloc()] or [sqli
182a0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 te3_realloc()] t
182b0 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 hat have.** not
182c0 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 yet been release
182d0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 d..**.** The app
182e0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f lication must no
182f0 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 t read or write
18300 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 any part of.** a
18310 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 block of memory
18320 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 after it has be
18330 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e en released usin
18340 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 g.** [sqlite3_fr
18350 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 ee()] or [sqlite
18360 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 3_realloc()]..*/
18370 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
18380 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 *sqlite3_malloc
18390 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 (int);.SQLITE_AP
183a0 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f I void *sqlite3_
183b0 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 realloc(void*, i
183c0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 nt);.SQLITE_API
183d0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 void sqlite3_fre
183e0 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a e(void*);../*.**
183f0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 CAPI3REF: Memor
18400 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 y Allocator Stat
18410 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c istics.**.** SQL
18420 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 ite provides the
18430 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 se two interface
18440 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 s for reporting
18450 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a on the status.**
18460 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
18470 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c _malloc()], [sql
18480 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e ite3_free()], an
18490 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c d [sqlite3_reall
184a0 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 oc()].** routine
184b0 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 s, which form th
184c0 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 e built-in memor
184d0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 y allocation sub
184e0 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 system..**.** ^T
184f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f he [sqlite3_memo
18500 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 ry_used()] routi
18510 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e ne returns the n
18520 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a umber of bytes.*
18530 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 * of memory curr
18540 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e ently outstandin
18550 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 g (malloced but
18560 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e not freed)..** ^
18570 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d The [sqlite3_mem
18580 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d ory_highwater()]
18590 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
185a0 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 the maximum.**
185b0 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 value of [sqlite
185c0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 3_memory_used()]
185d0 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d since the high-
185e0 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 water mark.** wa
185f0 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e s last reset. ^
18600 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 The values retur
18610 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ned by [sqlite3_
18620 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 memory_used()] a
18630 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d nd.** [sqlite3_m
18640 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 emory_highwater(
18650 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f )] include any o
18660 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 verhead.** added
18670 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 by SQLite in it
18680 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e s implementation
18690 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c of [sqlite3_mal
186a0 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e loc()],.** but n
186b0 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 ot overhead adde
186c0 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 d by the any und
186d0 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c erlying system l
186e0 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e ibrary.** routin
186f0 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 es that [sqlite3
18700 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 _malloc()] may c
18710 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 all..**.** ^The
18720 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 memory high-wate
18730 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 r mark is reset
18740 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 to the current v
18750 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 alue of.** [sqli
18760 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 te3_memory_used(
18770 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 )] if and only i
18780 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 f the parameter
18790 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d to.** [sqlite3_m
187a0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 emory_highwater(
187b0 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 )] is true. ^Th
187c0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
187d0 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f .** by [sqlite3_
187e0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 memory_highwater
187f0 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 (1)] is the high
18800 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 -water mark.** p
18810 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 rior to the rese
18820 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 t..*/.SQLITE_API
18830 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 sqlite3_int64 s
18840 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 qlite3_memory_us
18850 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 ed(void);.SQLITE
18860 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 _API sqlite3_int
18870 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 64 sqlite3_memor
18880 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 y_highwater(int
18890 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a resetFlag);../*.
188a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 ** CAPI3REF: Pse
188b0 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 udo-Random Numbe
188c0 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a r Generator.**.*
188d0 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e * SQLite contain
188e0 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 s a high-quality
188f0 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e pseudo-random n
18900 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 umber generator
18910 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a (PRNG) used to.*
18920 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 * select random
18930 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d [ROWID | ROWIDs]
18940 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 when inserting
18950 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f new records into
18960 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a a table that.**
18970 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 already uses th
18980 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 e largest possib
18990 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 le [ROWID]. The
189a0 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 PRNG is also us
189b0 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 ed for.** the bu
189c0 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 ild-in random()
189d0 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 and randomblob()
189e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 SQL functions.
189f0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 This interface
18a00 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 allows.** applic
18a10 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 ations to access
18a20 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 the same PRNG f
18a30 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 or other purpose
18a40 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c s..**.** ^A call
18a50 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 to this routine
18a60 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 stores N bytes
18a70 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e of randomness in
18a80 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a to buffer P..**.
18a90 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 ** ^The first ti
18aa0 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 me this routine
18ab0 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 is invoked (eith
18ac0 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 er internally or
18ad0 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 by.** the appli
18ae0 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 cation) the PRNG
18af0 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67 is seeded using
18b00 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 randomness obta
18b10 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 ined.** from the
18b20 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 xRandomness met
18b30 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 hod of the defau
18b40 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d lt [sqlite3_vfs]
18b50 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 object..** ^On
18b60 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 all subsequent i
18b70 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 nvocations, the
18b80 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 pseudo-randomnes
18b90 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a s is generated.*
18ba0 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 * internally and
18bb0 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 without recours
18bc0 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 e to the [sqlite
18bd0 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 3_vfs] xRandomne
18be0 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f ss.** method..*/
18bf0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
18c00 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e sqlite3_randomn
18c10 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 ess(int N, void
18c20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 *P);../*.** CAPI
18c30 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 3REF: Compile-Ti
18c40 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e me Authorization
18c50 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a Callbacks.**.**
18c60 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 ^This routine r
18c70 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 egisters an auth
18c80 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
18c90 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 with a particula
18ca0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 r.** [database c
18cb0 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 onnection], supp
18cc0 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 lied in the firs
18cd0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e t argument..** ^
18ce0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 The authorizer c
18cf0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
18d00 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d ed as SQL statem
18d10 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 ents are being c
18d20 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 ompiled.** by [s
18d30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
18d40 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 ] or its variant
18d50 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 s [sqlite3_prepa
18d60 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 re_v2()],.** [sq
18d70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
18d80 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
18d90 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e prepare16_v2()].
18da0 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a ^At various.**
18db0 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 points during t
18dc0 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 he compilation p
18dd0 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 rocess, as logic
18de0 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 is being create
18df0 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 d.** to perform
18e00 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c various actions,
18e10 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
18e20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
18e30 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 ked to.** see if
18e40 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 those actions a
18e50 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 re allowed. ^Th
18e60 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
18e70 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 lback should.**
18e80 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f return [SQLITE_O
18e90 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 K] to allow the
18ea0 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f action, [SQLITE_
18eb0 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c IGNORE] to disal
18ec0 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 low the.** speci
18ed0 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 fic action but a
18ee0 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 llow the SQL sta
18ef0 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e tement to contin
18f00 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 ue to be.** comp
18f10 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 iled, or [SQLITE
18f20 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 _DENY] to cause
18f30 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 the entire SQL s
18f40 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a tatement to be.*
18f50 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 * rejected with
18f60 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 an error. ^If t
18f70 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
18f80 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a llback returns.*
18f90 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 * any value othe
18fa0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 r than [SQLITE_I
18fb0 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f GNORE], [SQLITE_
18fc0 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f OK], or [SQLITE_
18fd0 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 DENY].** then th
18fe0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 e [sqlite3_prepa
18ff0 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 re_v2()] or equi
19000 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 valent call that
19010 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 triggered.** th
19020 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c e authorizer wil
19030 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 l fail with an e
19040 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a rror message..**
19050 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c .** When the cal
19060 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 lback returns [S
19070 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 QLITE_OK], that
19080 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 means the operat
19090 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 ion.** requested
190a0 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 is ok. ^When t
190b0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 he callback retu
190c0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 rns [SQLITE_DENY
190d0 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 ], the.** [sqlit
190e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
190f0 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 or equivalent c
19100 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 all that trigger
19110 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 ed the.** author
19120 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 izer will fail w
19130 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 ith an error mes
19140 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 sage explaining
19150 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 that.** access i
19160 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a s denied. .**.**
19170 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 ^The first para
19180 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 meter to the aut
19190 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
191a0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 is a copy of th
191b0 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d e third.** param
191c0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 eter to the sqli
191d0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
191e0 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 er() interface.
191f0 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 ^The second para
19200 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 meter.** to the
19210 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 callback is an i
19220 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 nteger [SQLITE_C
19230 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 OPY | action cod
19240 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 e] that specifie
19250 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 s.** the particu
19260 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 lar action to be
19270 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 authorized. ^Th
19280 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 e third through
19290 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 sixth parameters
192a0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 .** to the callb
192b0 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 ack are zero-ter
192c0 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 minated strings
192d0 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 that contain add
192e0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 itional.** detai
192f0 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 ls about the act
19300 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 ion to be author
19310 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 ized..**.** ^If
19320 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 the action code
19330 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d is [SQLITE_READ]
19340 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c .** and the call
19350 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 back returns [SQ
19360 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 LITE_IGNORE] the
19370 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 n the.** [prepar
19380 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 ed statement] st
19390 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 atement is const
193a0 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 ructed to substi
193b0 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 tute.** a NULL v
193c0 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 alue in place of
193d0 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d the table colum
193e0 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 n that would hav
193f0 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 e.** been read i
19400 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 f [SQLITE_OK] ha
19410 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e d been returned.
19420 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 The [SQLITE_IG
19430 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 NORE].** return
19440 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 can be used to d
19450 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 eny an untrusted
19460 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 user access to
19470 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f individual.** co
19480 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 lumns of a table
19490 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 ..** ^If the act
194a0 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c ion code is [SQL
194b0 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 ITE_DELETE] and
194c0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 the callback ret
194d0 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f urns.** [SQLITE_
194e0 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 IGNORE] then the
194f0 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 [DELETE] operat
19500 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 ion proceeds but
19510 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 the.** [truncat
19520 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 e optimization]
19530 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 is disabled and
19540 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c all rows are del
19550 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c eted individuall
19560 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 y..**.** An auth
19570 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 orizer is used w
19580 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 hen [sqlite3_pre
19590 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 pare | preparing
195a0 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 ].** SQL stateme
195b0 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 nts from an untr
195c0 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f usted source, to
195d0 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 ensure that the
195e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a SQL statements.
195f0 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f ** do not try to
19600 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 access data the
19610 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 y are not allowe
19620 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 d to see, or tha
19630 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a t they do not.**
19640 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 try to execute
19650 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d malicious statem
19660 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 ents that damage
19670 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 the database.
19680 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 For.** example,
19690 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d an application m
196a0 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 ay allow a user
196b0 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 to enter arbitra
196c0 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 ry.** SQL querie
196d0 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e s for evaluation
196e0 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 by a database.
196f0 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 But the applica
19700 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 tion does.** not
19710 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 want the user t
19720 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b o be able to mak
19730 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e e arbitrary chan
19740 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 ges to the.** da
19750 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 tabase. An auth
19760 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 orizer could the
19770 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 n be put in plac
19780 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 e while the.** u
19790 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 ser-entered SQL
197a0 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 is being [sqlite
197b0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 3_prepare | prep
197c0 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 ared] that.** di
197d0 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 sallows everythi
197e0 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 ng except [SELEC
197f0 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a T] statements..*
19800 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e *.** Application
19810 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 s that need to p
19820 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 rocess SQL from
19830 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 untrusted source
19840 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 s.** might also
19850 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e consider lowerin
19860 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 g resource limit
19870 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 s using [sqlite3
19880 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 _limit()].** and
19890 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 limiting databa
198a0 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 se size using th
198b0 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e e [max_page_coun
198c0 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 t] [PRAGMA].** i
198d0 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 n addition to us
198e0 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 ing an authorize
198f0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 r..**.** ^(Only
19900 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 a single authori
19910 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c zer can be in pl
19920 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 ace on a databas
19930 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
19940 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 at a time. Each
19950 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
19960 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 _set_authorizer
19970 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a overrides the.**
19980 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 previous call.)
19990 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 ^ ^Disable the
199a0 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e authorizer by in
199b0 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 stalling a NULL
199c0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 callback..** The
199d0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 authorizer is d
199e0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 isabled by defau
199f0 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 lt..**.** The au
19a00 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
19a10 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e k must not do an
19a20 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c ything that will
19a30 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 modify.** the d
19a40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
19a50 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 on that invoked
19a60 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
19a70 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 allback..** Note
19a80 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 that [sqlite3_p
19a90 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 repare_v2()] and
19aa0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
19ab0 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 ] both modify th
19ac0 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 eir.** database
19ad0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 connections for
19ae0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 the meaning of "
19af0 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 modify" in this
19b00 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a paragraph..**.**
19b10 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f ^When [sqlite3_
19b20 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 prepare_v2()] is
19b30 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 used to prepare
19b40 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 a statement, th
19b50 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d e.** statement m
19b60 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 ight be re-prepa
19b70 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 red during [sqli
19b80 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 te3_step()] due
19b90 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 to a .** schema
19ba0 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 change. Hence,
19bb0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
19bc0 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 should ensure th
19bd0 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 at the.** correc
19be0 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c t authorizer cal
19bf0 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e lback remains in
19c00 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 place during th
19c10 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 e [sqlite3_step(
19c20 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 )]..**.** ^Note
19c30 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 that the authori
19c40 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 zer callback is
19c50 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 invoked only dur
19c60 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
19c70 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 prepare()] or it
19c80 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 s variants. Aut
19c90 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f horization is no
19ca0 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 t.** performed d
19cb0 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 uring statement
19cc0 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 evaluation in [s
19cd0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 qlite3_step()],
19ce0 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 unless.** as sta
19cf0 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 ted in the previ
19d00 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 ous paragraph, s
19d10 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e qlite3_step() in
19d20 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 vokes.** sqlite3
19d30 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f _prepare_v2() to
19d40 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61 reprepare a sta
19d50 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 tement after a s
19d60 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f chema change..*/
19d70 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
19d80 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
19d90 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 orizer(. sqlite
19da0 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 3*,. int (*xAut
19db0 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e h)(void*,int,con
19dc0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 st char*,const c
19dd0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a har*,const char*
19de0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 ,const char*),.
19df0 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 void *pUserData
19e00 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
19e10 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 REF: Authorizer
19e20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a Return Codes.**.
19e30 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f ** The [sqlite3_
19e40 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c set_authorizer |
19e50 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
19e60 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d back function] m
19e70 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 ust.** return ei
19e80 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d ther [SQLITE_OK]
19e90 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 or one of these
19ea0 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 two constants i
19eb0 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 n order.** to si
19ec0 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 gnal SQLite whet
19ed0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 her or not the a
19ee0 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 ction is permitt
19ef0 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 ed. See the.**
19f00 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 [sqlite3_set_aut
19f10 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 horizer | author
19f20 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 izer documentati
19f30 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e on] for addition
19f40 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f al.** informatio
19f50 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 n..*/.#define SQ
19f60 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 LITE_DENY 1
19f70 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c /* Abort the SQL
19f80 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 statement with
19f90 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 an error */.#def
19fa0 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 ine SQLITE_IGNOR
19fb0 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 E 2 /* Don't a
19fc0 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 llow access, but
19fd0 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 don't generate
19fe0 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a an error */../*.
19ff0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 ** CAPI3REF: Aut
1a000 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 horizer Action C
1a010 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b odes.**.** The [
1a020 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
1a030 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 orizer()] interf
1a040 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 ace registers a
1a050 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
1a060 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 n.** that is inv
1a070 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a oked to authoriz
1a080 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 e certain SQL st
1a090 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e atement actions.
1a0a0 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 The.** second
1a0b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
1a0c0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 callback is an
1a0d0 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 integer code tha
1a0e0 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 t specifies.** w
1a0f0 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 hat action is be
1a100 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 ing authorized.
1a110 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 These are the i
1a120 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f nteger action co
1a130 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 des that.** the
1a140 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
1a150 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 ack may be passe
1a160 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 d..**.** These a
1a170 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 ction code value
1a180 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b s signify what k
1a190 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e ind of operation
1a1a0 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 is to be.** aut
1a1b0 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 horized. The 3r
1a1c0 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 d and 4th parame
1a1d0 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 ters to the auth
1a1e0 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c orization.** cal
1a1f0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 lback function w
1a200 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 ill be parameter
1a210 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 s or NULL depend
1a220 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 ing on which of
1a230 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 these.** codes i
1a240 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 s used as the se
1a250 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 cond parameter.
1a260 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d ^(The 5th param
1a270 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 eter to the.** a
1a280 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
1a290 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f ck is the name o
1a2a0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 f the database (
1a2b0 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a "main", "temp",.
1a2c0 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c ** etc.) if appl
1a2d0 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 icable.)^ ^The
1a2e0 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 6th parameter to
1a2f0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
1a300 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 callback.** is t
1a310 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 he name of the i
1a320 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 nner-most trigge
1a330 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 r or view that i
1a340 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f s responsible fo
1a350 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 r.** the access
1a360 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 attempt or NULL
1a370 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 if this access a
1a380 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 ttempt is direct
1a390 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c ly from.** top-l
1a3a0 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a evel SQL code..*
1a3b0 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a /./*************
1a3c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1a3d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 ************** 3
1a3e0 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 rd ************
1a3f0 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 4th ***********/
1a400 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1a410 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 CREATE_INDEX
1a420 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 1 /* Ind
1a430 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 ex Name Tab
1a440 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
1a450 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
1a460 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 REATE_TABLE
1a470 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 2 /* Tabl
1a480 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c e Name NULL
1a490 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
1a4a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
1a4b0 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 EATE_TEMP_INDEX
1a4c0 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 3 /* Index
1a4d0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 Name Table
1a4e0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
1a4f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
1a500 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 ATE_TEMP_TABLE
1a510 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4 /* Table
1a520 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
1a530 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
1a540 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
1a550 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 TE_TEMP_TRIGGER
1a560 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 5 /* Trigger
1a570 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e Name Table N
1a580 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
1a590 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
1a5a0 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 E_TEMP_VIEW
1a5b0 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 6 /* View Nam
1a5c0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 e NULL
1a5d0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
1a5e0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
1a5f0 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 _TRIGGER
1a600 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 7 /* Trigger N
1a610 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d ame Table Nam
1a620 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
1a630 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
1a640 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 VIEW 8
1a650 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 /* View Name
1a660 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
1a670 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
1a680 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 SQLITE_DELETE
1a690 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 9
1a6a0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
1a6b0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
1a6c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1a6d0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 SQLITE_DROP_INDE
1a6e0 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 X 10
1a6f0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 /* Index Name
1a700 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
1a710 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1a720 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 QLITE_DROP_TABLE
1a730 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 11
1a740 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
1a750 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
1a760 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1a770 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 LITE_DROP_TEMP_I
1a780 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f NDEX 12 /
1a790 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 * Index Name
1a7a0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
1a7b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1a7c0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 ITE_DROP_TEMP_TA
1a7d0 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a BLE 13 /*
1a7e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
1a7f0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
1a800 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1a810 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 TE_DROP_TEMP_TRI
1a820 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 GGER 14 /*
1a830 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 Trigger Name
1a840 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
1a850 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1a860 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 E_DROP_TEMP_VIEW
1a870 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 15 /* V
1a880 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e iew Name N
1a890 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
1a8a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1a8b0 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 _DROP_TRIGGER
1a8c0 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 16 /* Tr
1a8d0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 igger Name Ta
1a8e0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
1a8f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1a900 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 DROP_VIEW
1a910 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 17 /* Vie
1a920 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c w Name NUL
1a930 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
1a940 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
1a950 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 NSERT
1a960 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 18 /* Tabl
1a970 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c e Name NULL
1a980 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
1a990 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 define SQLITE_PR
1a9a0 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 AGMA
1a9b0 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 19 /* Pragm
1a9c0 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 a Name 1st a
1a9d0 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 rg or NULL */.#d
1a9e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 efine SQLITE_REA
1a9f0 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 D
1aa00 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 20 /* Table
1aa10 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e Name Column
1aa20 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
1aa30 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 fine SQLITE_SELE
1aa40 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 CT
1aa50 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 21 /* NULL
1aa60 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 NULL
1aa70 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
1aa80 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 ine SQLITE_TRANS
1aa90 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 ACTION
1aaa0 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 22 /* Operatio
1aab0 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 n NULL
1aac0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
1aad0 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 ne SQLITE_UPDATE
1aae0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 2
1aaf0 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 3 /* Table Nam
1ab00 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 e Column Na
1ab10 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e me */.#defin
1ab20 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 e SQLITE_ATTACH
1ab30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 24
1ab40 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 /* Filename
1ab50 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
1ab60 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
1ab70 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 SQLITE_DETACH
1ab80 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 25
1ab90 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 /* Database Na
1aba0 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 me NULL
1abb0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1abc0 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 SQLITE_ALTER_TAB
1abd0 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 LE 26
1abe0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d /* Database Nam
1abf0 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 e Table Name
1ac00 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1ac10 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 QLITE_REINDEX
1ac20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 27
1ac30 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 /* Index Name
1ac40 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
1ac50 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1ac60 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 LITE_ANALYZE
1ac70 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 28 /
1ac80 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
1ac90 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
1aca0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1acb0 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c ITE_CREATE_VTABL
1acc0 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a E 29 /*
1acd0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
1ace0 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 Module Name
1acf0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1ad00 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 TE_DROP_VTABLE
1ad10 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 30 /*
1ad20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
1ad30 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 Module Name
1ad40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1ad50 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 E_FUNCTION
1ad60 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 31 /* N
1ad70 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 ULL F
1ad80 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a unction Name *
1ad90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1ada0 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 _SAVEPOINT
1adb0 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 32 /* Op
1adc0 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 eration Sa
1add0 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f vepoint Name */
1ade0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1adf0 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 COPY
1ae00 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 0 /* No
1ae10 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a longer used */..
1ae20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1ae30 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 Tracing And Prof
1ae40 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a iling Functions.
1ae50 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
1ae60 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 ines register ca
1ae70 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 llback functions
1ae80 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 that can be use
1ae90 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 d for.** tracing
1aea0 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 and profiling t
1aeb0 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 he execution of
1aec0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a SQL statements..
1aed0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 **.** ^The callb
1aee0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 ack function reg
1aef0 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 istered by sqlit
1af00 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e e3_trace() is in
1af10 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 voked at.** vari
1af20 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 ous times when a
1af30 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 n SQL statement
1af40 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 is being run by
1af50 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
1af60 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 ..** ^The sqlite
1af70 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 3_trace() callba
1af80 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 ck is invoked wi
1af90 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 th a UTF-8 rende
1afa0 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 ring of the.** S
1afb0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 QL statement tex
1afc0 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 t as the stateme
1afd0 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 nt first begins
1afe0 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 executing..** ^(
1aff0 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 Additional sqlit
1b000 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 e3_trace() callb
1b010 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 acks might occur
1b020 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 .** as each trig
1b030 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d gered subprogram
1b040 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 is entered. Th
1b050 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 e callbacks for
1b060 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 triggers.** cont
1b070 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 ain a UTF-8 SQL
1b080 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 comment that ide
1b090 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 ntifies the trig
1b0a0 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ger.)^.**.** ^Th
1b0b0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
1b0c0 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 ion registered b
1b0d0 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c y sqlite3_profil
1b0e0 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a e() is invoked.*
1b0f0 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 * as each SQL st
1b100 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 atement finishes
1b110 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 . ^The profile
1b120 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e callback contain
1b130 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 s.** the origina
1b140 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 l statement text
1b150 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 and an estimate
1b160 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 of wall-clock t
1b170 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f ime.** of how lo
1b180 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e ng that statemen
1b190 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 t took to run.
1b1a0 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c ^The profile cal
1b1b0 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 lback.** time is
1b1c0 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e in units of nan
1b1d0 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 oseconds, howeve
1b1e0 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d r the current im
1b1f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 plementation.**
1b200 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 is only capable
1b210 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 of millisecond r
1b220 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 esolution so the
1b230 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 six least signi
1b240 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 ficant.** digits
1b250 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 in the time are
1b260 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 meaningless. F
1b270 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f uture versions o
1b280 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 f SQLite.** migh
1b290 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 t provide greate
1b2a0 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 r resolution on
1b2b0 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c the profiler cal
1b2c0 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 lback. The.** s
1b2d0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 qlite3_profile()
1b2e0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e function is con
1b2f0 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 sidered experime
1b300 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 ntal and is.** s
1b310 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 ubject to change
1b320 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 in future versi
1b330 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a ons of SQLite..*
1b340 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 /.SQLITE_API voi
1b350 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 d *sqlite3_trace
1b360 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 (sqlite3*, void(
1b370 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 *xTrace)(void*,c
1b380 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 onst char*), voi
1b390 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 d*);.SQLITE_API
1b3a0 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e SQLITE_EXPERIMEN
1b3b0 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 TAL void *sqlite
1b3c0 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 3_profile(sqlite
1b3d0 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 3*,. void(*xPr
1b3e0 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e ofile)(void*,con
1b3f0 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 st char*,sqlite3
1b400 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 _uint64), void*)
1b410 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1b420 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 F: Query Progres
1b430 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a s Callbacks.**.*
1b440 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 * ^The sqlite3_p
1b450 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 rogress_handler(
1b460 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 D,N,X,P) interfa
1b470 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61 ce causes the ca
1b480 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 llback.** functi
1b490 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b on X to be invok
1b4a0 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 ed periodically
1b4b0 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e during long runn
1b4c0 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 ing calls to.**
1b4d0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
1b4e0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 , [sqlite3_step(
1b4f0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
1b500 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 get_table()] for
1b510 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
1b520 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 nection D. An e
1b530 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 xample use for t
1b540 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 his.** interface
1b550 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 is to keep a GU
1b560 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 I updated during
1b570 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a a large query..
1b580 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d **.** ^The param
1b590 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64 eter P is passed
1b5a0 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 through as the
1b5b0 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 only parameter t
1b5c0 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 o the .** callba
1b5d0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 ck function X.
1b5e0 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e ^The parameter N
1b5f0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f is the number o
1b600 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d f .** [virtual m
1b610 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 achine instructi
1b620 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 ons] that are ev
1b630 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 aluated between
1b640 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e successive.** in
1b650 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 vocations of the
1b660 20 63 61 6c 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a callback X..**.
1b670 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c ** ^Only a singl
1b680 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c e progress handl
1b690 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 er may be define
1b6a0 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 d at one time pe
1b6b0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 r.** [database c
1b6c0 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 onnection]; sett
1b6d0 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 ing a new progre
1b6e0 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 ss handler cance
1b6f0 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e ls the.** old on
1b700 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 e. ^Setting par
1b710 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c ameter X to NULL
1b720 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 disables the pr
1b730 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a ogress handler..
1b740 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 ** ^The progress
1b750 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f handler is also
1b760 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 disabled by set
1b770 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 ting N to a valu
1b780 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 e less.** than 1
1b790 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
1b7a0 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 progress callbac
1b7b0 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 k returns non-ze
1b7c0 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f ro, the operatio
1b7d0 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 n is.** interrup
1b7e0 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 ted. This featu
1b7f0 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 re can be used t
1b800 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a o implement a.**
1b810 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e "Cancel" button
1b820 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 on a GUI progre
1b830 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a ss dialog box..*
1b840 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 *.** The progres
1b850 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 s handler callba
1b860 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 ck must not do a
1b870 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c nything that wil
1b880 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 l modify.** the
1b890 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1b8a0 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 ion that invoked
1b8b0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 the progress ha
1b8c0 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 ndler..** Note t
1b8d0 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 hat [sqlite3_pre
1b8e0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b pare_v2()] and [
1b8f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
1b900 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 both modify thei
1b910 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f r.** database co
1b920 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 nnections for th
1b930 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f e meaning of "mo
1b940 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 dify" in this pa
1b950 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53 ragraph..**.*/.S
1b960 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
1b970 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f qlite3_progress_
1b980 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a handler(sqlite3*
1b990 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f , int, int(*)(vo
1b9a0 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f id*), void*);../
1b9b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
1b9c0 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 pening A New Dat
1b9d0 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e abase Connection
1b9e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f .**.** ^These ro
1b9f0 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 utines open an S
1ba00 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 QLite database f
1ba10 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20 69 ile whose name i
1ba20 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a 2a s given by the.*
1ba30 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d * filename argum
1ba40 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 ent. ^The filena
1ba50 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 me argument is i
1ba60 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 nterpreted as UT
1ba70 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 F-8 for.** sqlit
1ba80 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 e3_open() and sq
1ba90 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
1baa0 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e and as UTF-16 in
1bab0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 the native byte
1bac0 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 .** order for sq
1bad0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 lite3_open16().
1bae0 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f ^(A [database co
1baf0 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 nnection] handle
1bb00 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 is usually.** r
1bb10 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 eturned in *ppDb
1bb20 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 , even if an err
1bb30 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 or occurs. The
1bb40 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 only exception i
1bb50 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c s that.** if SQL
1bb60 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f ite is unable to
1bb70 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 allocate memory
1bb80 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 to hold the [sq
1bb90 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a lite3] object,.*
1bba0 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 * a NULL will be
1bbb0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 written into *p
1bbc0 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 pDb instead of a
1bbd0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
1bbe0 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a [sqlite3].** obj
1bbf0 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 ect.)^ ^(If the
1bc00 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e database is open
1bc10 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 ed (and/or creat
1bc20 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 ed) successfully
1bc30 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 , then.** [SQLIT
1bc40 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 E_OK] is returne
1bc50 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e d. Otherwise an
1bc60 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 [error code] is
1bc70 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 returned.)^ ^Th
1bc80 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 e.** [sqlite3_er
1bc90 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 rmsg()] or [sqli
1bca0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 te3_errmsg16()]
1bcb0 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 routines can be
1bcc0 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a used to obtain.*
1bcd0 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e * an English lan
1bce0 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f guage descriptio
1bcf0 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 n of the error f
1bd00 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 ollowing a failu
1bd10 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 re of any.** of
1bd20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e the sqlite3_open
1bd30 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a () routines..**.
1bd40 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 ** ^The default
1bd50 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 encoding for the
1bd60 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 database will b
1bd70 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 e UTF-8 if.** sq
1bd80 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 lite3_open() or
1bd90 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
1bda0 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a ) is called and.
1bdb0 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 ** UTF-16 in the
1bdc0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 native byte ord
1bdd0 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 er if sqlite3_op
1bde0 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a en16() is used..
1bdf0 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 **.** Whether or
1be00 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 not an error oc
1be10 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 curs when it is
1be20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 opened, resource
1be30 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 s.** associated
1be40 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 with the [databa
1be50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 se connection] h
1be60 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 andle should be
1be70 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 released by.** p
1be80 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 assing it to [sq
1be90 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 lite3_close()] w
1bea0 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e hen it is no lon
1beb0 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a ger required..**
1bec0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
1bed0 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 open_v2() interf
1bee0 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 ace works like s
1bef0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a qlite3_open().**
1bf00 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 except that it
1bf10 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 accepts two addi
1bf20 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 tional parameter
1bf30 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c s for additional
1bf40 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 control.** over
1bf50 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 the new databas
1bf60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e e connection. ^
1bf70 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d (The flags param
1bf80 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 eter to.** sqlit
1bf90 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e e3_open_v2() can
1bfa0 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 take one of.**
1bfb0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 the following th
1bfc0 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 ree values, opti
1bfd0 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 onally combined
1bfe0 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 with the .** [SQ
1bff0 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 LITE_OPEN_NOMUTE
1c000 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e X], [SQLITE_OPEN
1c010 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 _FULLMUTEX], [SQ
1c020 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 LITE_OPEN_SHARED
1c030 43 41 43 48 45 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f CACHE],.** and/o
1c040 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 r [SQLITE_OPEN_P
1c050 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 RIVATECACHE] fla
1c060 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e gs:)^.**.** <dl>
1c070 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 .** ^(<dt>[SQLIT
1c080 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d E_OPEN_READONLY]
1c090 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
1c0a0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
1c0b0 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 ned in read-only
1c0c0 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 mode. If the d
1c0d0 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 atabase does not
1c0e0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 .** already exis
1c0f0 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 t, an error is r
1c100 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a eturned.</dd>)^.
1c110 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c **.** ^(<dt>[SQL
1c120 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 ITE_OPEN_READWRI
1c130 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e TE]</dt>.** <dd>
1c140 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 The database is
1c150 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 opened for readi
1c160 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 ng and writing i
1c170 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 f possible, or r
1c180 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 eading.** only i
1c190 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 f the file is wr
1c1a0 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 ite protected by
1c1b0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 the operating s
1c1c0 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 ystem. In eithe
1c1d0 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 r.** case the da
1c1e0 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 tabase must alre
1c1f0 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 ady exist, other
1c200 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 wise an error is
1c210 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 returned.</dd>)
1c220 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 ^.**.** ^(<dt>[S
1c230 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
1c240 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f RITE] | [SQLITE_
1c250 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 OPEN_CREATE]</dt
1c260 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 >.** <dd>The dat
1c270 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 abase is opened
1c280 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 for reading and
1c290 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 writing, and is
1c2a0 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 created if.** it
1c2b0 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 does not alread
1c2c0 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 y exist. This is
1c2d0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 the behavior th
1c2e0 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 at is always use
1c2f0 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 d for.** sqlite3
1c300 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 _open() and sqli
1c310 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 te3_open16().</d
1c320 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a d>)^.** </dl>.**
1c330 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 .** If the 3rd p
1c340 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
1c350 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 te3_open_v2() is
1c360 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a not one of the.
1c370 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 ** combinations
1c380 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f shown above or o
1c390 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e ne of the combin
1c3a0 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f ations shown abo
1c3b0 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 ve combined.** w
1c3c0 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ith the [SQLITE_
1c3d0 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b OPEN_NOMUTEX], [
1c3e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c SQLITE_OPEN_FULL
1c3f0 4d 55 54 45 58 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 MUTEX],.** [SQLI
1c400 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 TE_OPEN_SHAREDCA
1c410 43 48 45 5d 20 61 6e 64 2f 6f 72 20 5b 53 51 4c CHE] and/or [SQL
1c420 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 ITE_OPEN_PRIVATE
1c430 43 41 43 48 45 5d 20 66 6c 61 67 73 2c 0a 2a 2a CACHE] flags,.**
1c440 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 then the behavi
1c450 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e or is undefined.
1c460 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b .**.** ^If the [
1c470 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 SQLITE_OPEN_NOMU
1c480 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 TEX] flag is set
1c490 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 , then the datab
1c4a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase connection.*
1c4b0 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d * opens in the m
1c4c0 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 ulti-thread [thr
1c4d0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 eading mode] as
1c4e0 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 long as the sing
1c4f0 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 le-thread.** mod
1c500 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 e has not been s
1c510 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 et at compile-ti
1c520 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 me or start-time
1c530 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 . ^If the.** [S
1c540 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d QLITE_OPEN_FULLM
1c550 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 UTEX] flag is se
1c560 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 t then the datab
1c570 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f ase connection o
1c580 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 pens.** in the s
1c590 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 erialized [threa
1c5a0 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 ding mode] unles
1c5b0 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 s single-thread
1c5c0 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c was.** previousl
1c5d0 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f y selected at co
1c5e0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 mpile-time or st
1c5f0 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 art-time..** ^Th
1c600 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 e [SQLITE_OPEN_S
1c610 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 HAREDCACHE] flag
1c620 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 causes the data
1c630 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
1c640 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c to be.** eligibl
1c650 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 e to use [shared
1c660 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 cache mode], re
1c670 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 gardless of whet
1c680 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 her or not share
1c690 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e d.** cache is en
1c6a0 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c abled using [sql
1c6b0 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 ite3_enable_shar
1c6c0 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 ed_cache()]. ^T
1c6d0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 he.** [SQLITE_OP
1c6e0 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d EN_PRIVATECACHE]
1c6f0 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 flag causes the
1c700 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
1c710 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 tion to not.** p
1c720 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 articipate in [s
1c730 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 hared cache mode
1c740 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 ] even if it is
1c750 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e enabled..**.** ^
1c760 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 If the filename
1c770 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 is ":memory:", t
1c780 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 hen a private, t
1c790 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f emporary in-memo
1c7a0 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 ry database.** i
1c7b0 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 s created for th
1c7c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e e connection. ^
1c7d0 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 This in-memory d
1c7e0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e atabase will van
1c7f0 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 ish when.** the
1c800 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1c810 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 ion is closed.
1c820 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 Future versions
1c830 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a of SQLite might.
1c840 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 ** make use of a
1c850 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 dditional specia
1c860 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 l filenames that
1c870 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 begin with the
1c880 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a ":" character..*
1c890 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e * It is recommen
1c8a0 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 ded that when a
1c8b0 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d database filenam
1c8c0 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 e actually does
1c8d0 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 begin with.** a
1c8e0 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f ":" character yo
1c8f0 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 u should prefix
1c900 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 the filename wit
1c910 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 h a pathname suc
1c920 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 h as.** "./" to
1c930 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e avoid ambiguity.
1c940 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 .**.** ^If the f
1c950 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d ilename is an em
1c960 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e pty string, then
1c970 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 a private, temp
1c980 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b orary.** on-disk
1c990 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 database will b
1c9a0 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 e created. ^Thi
1c9b0 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61 s private databa
1c9c0 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 se will be.** au
1c9d0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 tomatically dele
1c9e0 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 ted as soon as t
1c9f0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
1ca00 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 ection is closed
1ca10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 ..**.** ^The fou
1ca20 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f rth parameter to
1ca30 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
1ca40 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f () is the name o
1ca50 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 f the.** [sqlite
1ca60 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 3_vfs] object th
1ca70 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f at defines the o
1ca80 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 perating system
1ca90 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a interface that.*
1caa0 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 * the new databa
1cab0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 se connection sh
1cac0 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 ould use. ^If t
1cad0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
1cae0 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c ter is.** a NULL
1caf0 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 pointer then th
1cb00 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 e default [sqlit
1cb10 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 e3_vfs] object i
1cb20 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 s used..**.** <b
1cb30 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 >Note to Windows
1cb40 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 users:</b> The
1cb50 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 encoding used f
1cb60 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 or the filename
1cb70 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 argument.** of s
1cb80 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e qlite3_open() an
1cb90 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 d sqlite3_open_v
1cba0 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 2() must be UTF-
1cbb0 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 8, not whatever.
1cbc0 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 ** codepage is c
1cbd0 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 urrently defined
1cbe0 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e . Filenames con
1cbf0 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 taining internat
1cc00 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 ional.** charact
1cc10 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 ers must be conv
1cc20 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 erted to UTF-8 p
1cc30 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 rior to passing
1cc40 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c them into.** sql
1cc50 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 ite3_open() or s
1cc60 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
1cc70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
1cc80 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e int sqlite3_open
1cc90 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a (. const char *
1cca0 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 filename, /* D
1ccb0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 atabase filename
1ccc0 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 (UTF-8) */. sq
1ccd0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 lite3 **ppDb
1cce0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 /* OUT: SQ
1ccf0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a Lite db handle *
1cd00 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 /.);.SQLITE_API
1cd10 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e int sqlite3_open
1cd20 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 16(. const void
1cd30 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a *filename, /*
1cd40 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 Database filena
1cd50 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 me (UTF-16) */.
1cd60 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 sqlite3 **ppDb
1cd70 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a /* OUT:
1cd80 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c SQLite db handl
1cd90 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 e */.);.SQLITE_A
1cda0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f PI int sqlite3_o
1cdb0 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 pen_v2(. const
1cdc0 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 char *filename,
1cdd0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 /* Database fi
1cde0 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a lename (UTF-8) *
1cdf0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 /. sqlite3 **pp
1ce00 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f Db, /* O
1ce10 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 UT: SQLite db ha
1ce20 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c ndle */. int fl
1ce30 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 ags,
1ce40 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 /* Flags */.
1ce50 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 const char *zVfs
1ce60 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 /* Name
1ce70 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f of VFS module to
1ce80 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a use */.);../*.*
1ce90 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f * CAPI3REF: Erro
1cea0 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 r Codes And Mess
1ceb0 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ages.**.** ^The
1cec0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 sqlite3_errcode(
1ced0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
1cee0 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 rns the numeric
1cef0 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 [result code] or
1cf00 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 .** [extended re
1cf10 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 sult code] for t
1cf20 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 he most recent f
1cf30 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 ailed sqlite3_*
1cf40 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f API call.** asso
1cf50 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 ciated with a [d
1cf60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1cf70 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 on]. If a prior
1cf80 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a API call failed.
1cf90 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 ** but the most
1cfa0 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 recent API call
1cfb0 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 succeeded, the r
1cfc0 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d eturn value from
1cfd0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 .** sqlite3_errc
1cfe0 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e ode() is undefin
1cff0 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 ed. ^The sqlite
1d000 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 3_extended_errco
1d010 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 de().** interfac
1d020 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 e is the same ex
1d030 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 cept that it alw
1d040 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 ays returns the
1d050 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 .** [extended re
1d060 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 sult code] even
1d070 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 when extended re
1d080 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a sult codes are.*
1d090 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a * disabled..**.*
1d0a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 * ^The sqlite3_e
1d0b0 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 rrmsg() and sqli
1d0c0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 te3_errmsg16() r
1d0d0 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 eturn English-la
1d0e0 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 nguage.** text t
1d0f0 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 hat describes th
1d100 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 e error, as eith
1d110 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d er UTF-8 or UTF-
1d120 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 16 respectively.
1d130 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 .** ^(Memory to
1d140 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d hold the error m
1d150 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 essage string is
1d160 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 managed interna
1d170 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c lly..** The appl
1d180 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 ication does not
1d190 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 need to worry a
1d1a0 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 bout freeing the
1d1b0 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 result..** Howe
1d1c0 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 ver, the error s
1d1d0 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f tring might be o
1d1e0 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 verwritten or de
1d1f0 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 allocated by.**
1d200 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 subsequent calls
1d210 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 to other SQLite
1d220 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 interface funct
1d230 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 ions.)^.**.** Wh
1d240 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 en the serialize
1d250 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 d [threading mod
1d260 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 e] is in use, it
1d270 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a might be the.**
1d280 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63 case that a sec
1d290 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 ond error occurs
1d2a0 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 on a separate t
1d2b0 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e hread in between
1d2c0 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 .** the time of
1d2d0 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 the first error
1d2e0 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 and the call to
1d2f0 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 these interfaces
1d300 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 ..** When that h
1d310 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f appens, the seco
1d320 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 nd error will be
1d330 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 reported since
1d340 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 these.** interfa
1d350 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 ces always repor
1d360 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e t the most recen
1d370 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 t result. To av
1d380 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 oid.** this, eac
1d390 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 h thread can obt
1d3a0 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 ain exclusive us
1d3b0 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 e of the [databa
1d3c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
1d3d0 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 .** by invoking
1d3e0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 [sqlite3_mutex_e
1d3f0 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 nter]([sqlite3_d
1d400 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 b_mutex](D)) bef
1d410 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a ore beginning.**
1d420 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e to use D and in
1d430 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f voking [sqlite3_
1d440 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 mutex_leave]([sq
1d450 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 lite3_db_mutex](
1d460 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c D)) after.** all
1d470 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e calls to the in
1d480 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 terfaces listed
1d490 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 here are complet
1d4a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 ed..**.** If an
1d4b0 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 interface fails
1d4c0 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 with SQLITE_MISU
1d4d0 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 SE, that means t
1d4e0 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 he interface.**
1d4f0 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f was invoked inco
1d500 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 rrectly by the a
1d510 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 pplication. In
1d520 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a that case, the.*
1d530 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 * error code and
1d540 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 message may or
1d550 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a may not be set..
1d560 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
1d570 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 t sqlite3_errcod
1d580 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a e(sqlite3 *db);.
1d590 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
1d5a0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f qlite3_extended_
1d5b0 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 errcode(sqlite3
1d5c0 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 *db);.SQLITE_API
1d5d0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c const char *sql
1d5e0 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 ite3_errmsg(sqli
1d5f0 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 te3*);.SQLITE_AP
1d600 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 I const void *sq
1d610 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 lite3_errmsg16(s
1d620 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
1d630 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 CAPI3REF: SQL S
1d640 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a tatement Object.
1d650 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 ** KEYWORDS: {pr
1d660 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1d670 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 } {prepared stat
1d680 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e ements}.**.** An
1d690 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 instance of thi
1d6a0 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 s object represe
1d6b0 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c nts a single SQL
1d6c0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 statement..** T
1d6d0 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 his object is va
1d6e0 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 riously known as
1d6f0 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61 a "prepared sta
1d700 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 tement" or a.**
1d710 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 "compiled SQL st
1d720 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 atement" or simp
1d730 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 ly as a "stateme
1d740 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c nt"..**.** The l
1d750 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 ife of a stateme
1d760 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 nt object goes s
1d770 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 omething like th
1d780 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a is:.**.** <ol>.*
1d790 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 * <li> Create th
1d7a0 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b e object using [
1d7b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
1d7c0 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 v2()] or a relat
1d7d0 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 ed.** funct
1d7e0 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e ion..** <li> Bin
1d7f0 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 d values to [hos
1d800 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 t parameters] us
1d810 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f ing the sqlite3_
1d820 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 bind_*().**
1d830 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 interfaces..**
1d840 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c <li> Run the SQL
1d850 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c by calling [sql
1d860 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 ite3_step()] one
1d870 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a or more times..
1d880 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 ** <li> Reset th
1d890 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e e statement usin
1d8a0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 g [sqlite3_reset
1d8b0 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b ()] then go back
1d8c0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 .** to step
1d8d0 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 2. Do this zer
1d8e0 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e o or more times.
1d8f0 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 .** <li> Destroy
1d900 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e the object usin
1d910 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c g [sqlite3_final
1d920 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e ize()]..** </ol>
1d930 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 .**.** Refer to
1d940 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e documentation on
1d950 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 individual meth
1d960 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 ods above for ad
1d970 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f ditional.** info
1d980 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 rmation..*/.type
1d990 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
1d9a0 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f e3_stmt sqlite3_
1d9b0 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 stmt;../*.** CAP
1d9c0 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 I3REF: Run-time
1d9d0 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 Limits.**.** ^(T
1d9e0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c his interface al
1d9f0 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 lows the size of
1da00 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 various constru
1da10 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 cts to be limite
1da20 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 d.** on a connec
1da30 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 tion by connecti
1da40 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 on basis. The f
1da50 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 irst parameter i
1da60 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 s the.** [databa
1da70 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 se connection] w
1da80 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f hose limit is to
1da90 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 be set or queri
1daa0 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f ed. The.** seco
1dab0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
1dac0 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 one of the [limi
1dad0 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 t categories] th
1dae0 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 at define a.** c
1daf0 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 lass of construc
1db00 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 ts to be size li
1db10 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 mited. The thir
1db20 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 d parameter is t
1db30 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 he.** new limit
1db40 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 for that constru
1db50 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 ct.)^.**.** ^If
1db60 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 the new limit is
1db70 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 a negative numb
1db80 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 er, the limit is
1db90 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e unchanged..** ^
1dba0 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 (For each limit
1dbb0 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f category SQLITE_
1dbc0 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 LIMIT_<i>NAME</i
1dbd0 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a > there is a .**
1dbe0 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 [limits | hard
1dbf0 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 upper bound].**
1dc00 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 set at compile-t
1dc10 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72 ime by a C prepr
1dc20 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 ocessor macro ca
1dc30 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 lled.** [limits
1dc40 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e | SQLITE_MAX_<i>
1dc50 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 NAME</i>]..** (T
1dc60 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 he "_LIMIT_" in
1dc70 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e the name is chan
1dc80 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 ged to "_MAX_".)
1dc90 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 )^.** ^Attempts
1dca0 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 to increase a li
1dcb0 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 mit above its ha
1dcc0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 rd upper bound a
1dcd0 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 re.** silently t
1dce0 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 runcated to the
1dcf0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 hard upper bound
1dd00 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c ..**.** ^Regardl
1dd10 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f ess of whether o
1dd20 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 r not the limit
1dd30 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 was changed, the
1dd40 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 .** [sqlite3_li
1dd50 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 mit()] interface
1dd60 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 returns the pri
1dd70 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 or value of the
1dd80 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 limit..** ^Hence
1dd90 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 , to find the cu
1dda0 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 rrent value of a
1ddb0 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 limit without c
1ddc0 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 hanging it,.** s
1ddd0 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 imply invoke thi
1dde0 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 s interface with
1ddf0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d the third param
1de00 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a eter set to -1..
1de10 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c **.** Run-time l
1de20 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 imits are intend
1de30 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 ed for use in ap
1de40 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 plications that
1de50 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 manage.** both t
1de60 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 heir own interna
1de70 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 l database and a
1de80 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 lso databases th
1de90 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 at are controlle
1dea0 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 d.** by untruste
1deb0 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 d external sourc
1dec0 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 es. An example
1ded0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 application migh
1dee0 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 t be a.** web br
1def0 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 owser that has i
1df00 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 ts own databases
1df10 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 for storing his
1df20 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 tory and.** sepa
1df30 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 rate databases c
1df40 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 ontrolled by Jav
1df50 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 aScript applicat
1df60 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a ions downloaded.
1df70 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 ** off the Inter
1df80 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e net. The intern
1df90 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e al databases can
1dfa0 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a be given the.**
1dfb0 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 large, default
1dfc0 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 limits. Databas
1dfd0 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 es managed by ex
1dfe0 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 ternal sources c
1dff0 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d an.** be given m
1e000 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 uch smaller limi
1e010 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 ts designed to p
1e020 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 revent a denial
1e030 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 of service.** at
1e040 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 tack. Developer
1e050 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e s might also wan
1e060 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 t to use the [sq
1e070 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
1e080 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 izer()].** inter
1e090 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 face to further
1e0a0 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 control untruste
1e0b0 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 d SQL. The size
1e0c0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
1e0d0 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 .** created by a
1e0e0 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 n untrusted scri
1e0f0 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 pt can be contai
1e100 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a ned using the.**
1e110 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 [max_page_count
1e120 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a ] [PRAGMA]..**.*
1e130 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c * New run-time l
1e140 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 imit categories
1e150 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 may be added in
1e160 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e future releases.
1e170 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
1e180 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 nt sqlite3_limit
1e190 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 (sqlite3*, int i
1e1a0 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a d, int newVal);.
1e1b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1e1c0 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 Run-Time Limit
1e1d0 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 Categories.** KE
1e1e0 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 YWORDS: {limit c
1e1f0 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 ategory} {*limit
1e200 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a categories}.**.
1e210 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e ** These constan
1e220 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 ts define variou
1e230 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 s performance li
1e240 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e mits.** that can
1e250 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 be lowered at r
1e260 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 un-time using [s
1e270 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e qlite3_limit()].
1e280 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 .** The synopsis
1e290 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 of the meanings
1e2a0 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 of the various
1e2b0 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 limits is shown
1e2c0 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 below..** Additi
1e2d0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
1e2e0 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 is available at
1e2f0 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 [limits | Limit
1e300 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a s in SQLite]..**
1e310 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 .** <dl>.** ^(<d
1e320 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c t>SQLITE_LIMIT_L
1e330 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ENGTH</dt>.** <d
1e340 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 d>The maximum si
1e350 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 ze of any string
1e360 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c or BLOB or tabl
1e370 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e e row, in bytes.
1e380 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c <dd>)^.**.** ^(<
1e390 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
1e3a0 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a SQL_LENGTH</dt>.
1e3b0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
1e3c0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 um length of an
1e3d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 SQL statement, i
1e3e0 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a n bytes.</dd>)^.
1e3f0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 **.** ^(<dt>SQLI
1e400 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c TE_LIMIT_COLUMN<
1e410 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
1e420 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
1e430 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 f columns in a t
1e440 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 able definition
1e450 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 or in the.** res
1e460 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 ult set of a [SE
1e470 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 LECT] or the max
1e480 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 imum number of c
1e490 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 olumns in an ind
1e4a0 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f ex.** or in an O
1e4b0 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 RDER BY or GROUP
1e4c0 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e BY clause.</dd>
1e4d0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 )^.**.** ^(<dt>S
1e4e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 QLITE_LIMIT_EXPR
1e4f0 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c _DEPTH</dt>.** <
1e500 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 dd>The maximum d
1e510 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 epth of the pars
1e520 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 e tree on any ex
1e530 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e pression.</dd>)^
1e540 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c .**.** ^(<dt>SQL
1e550 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 ITE_LIMIT_COMPOU
1e560 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a ND_SELECT</dt>.*
1e570 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
1e580 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d m number of term
1e590 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 s in a compound
1e5a0 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 SELECT statement
1e5b0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e .</dd>)^.**.** ^
1e5c0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
1e5d0 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a T_VDBE_OP</dt>.*
1e5e0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
1e5f0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 m number of inst
1e600 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 ructions in a vi
1e610 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 rtual machine pr
1e620 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f ogram.** used to
1e630 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 implement an SQ
1e640 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 L statement. Th
1e650 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 is limit is not
1e660 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 currently.** enf
1e670 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 orced, though th
1e680 61 74 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 at might be adde
1e690 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 d in some future
1e6a0 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 release of.** S
1e6b0 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a QLite.</dd>)^.**
1e6c0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 .** ^(<dt>SQLITE
1e6d0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f _LIMIT_FUNCTION_
1e6e0 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ARG</dt>.** <dd>
1e6f0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
1e700 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 er of arguments
1e710 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f on a function.</
1e720 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 dd>)^.**.** ^(<d
1e730 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 t>SQLITE_LIMIT_A
1e740 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 TTACHED</dt>.**
1e750 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
1e760 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 number of [ATTAC
1e770 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 H | attached dat
1e780 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a abases].)^</dd>.
1e790 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 **.** ^(<dt>SQLI
1e7a0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 TE_LIMIT_LIKE_PA
1e7b0 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 TTERN_LENGTH</dt
1e7c0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
1e7d0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 imum length of t
1e7e0 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d he pattern argum
1e7f0 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 ent to the [LIKE
1e800 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f ] or.** [GLOB] o
1e810 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e perators.</dd>)^
1e820 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c .**.** ^(<dt>SQL
1e830 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 ITE_LIMIT_VARIAB
1e840 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a LE_NUMBER</dt>.*
1e850 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
1e860 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f m index number o
1e870 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 f any [parameter
1e880 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 ] in an SQL stat
1e890 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e ement.)^.**.** ^
1e8a0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
1e8b0 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c T_TRIGGER_DEPTH<
1e8c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
1e8d0 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 maximum depth of
1e8e0 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 recursion for t
1e8f0 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a riggers.</dd>)^.
1e900 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 ** </dl>.*/.#def
1e910 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
1e920 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 _LENGTH
1e930 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 0.#de
1e940 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
1e950 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 T_SQL_LENGTH
1e960 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 1.#d
1e970 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
1e980 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 IT_COLUMN
1e990 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 2.#
1e9a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
1e9b0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 MIT_EXPR_DEPTH
1e9c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 3.
1e9d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
1e9e0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 IMIT_COMPOUND_SE
1e9f0 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34 LECT 4
1ea00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1ea10 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 LIMIT_VDBE_OP
1ea20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1ea30 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5.#define SQLITE
1ea40 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f _LIMIT_FUNCTION_
1ea50 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20 ARG
1ea60 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 6.#define SQLIT
1ea70 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 E_LIMIT_ATTACHED
1ea80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1ea90 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 7.#define SQLI
1eaa0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 TE_LIMIT_LIKE_PA
1eab0 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 TTERN_LENGTH
1eac0 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 8.#define SQL
1ead0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 ITE_LIMIT_VARIAB
1eae0 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 LE_NUMBER
1eaf0 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 9.#define SQ
1eb00 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 LITE_LIMIT_TRIGG
1eb10 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 ER_DEPTH
1eb20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 10../*.** CA
1eb30 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e PI3REF: Compilin
1eb40 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 g An SQL Stateme
1eb50 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 nt.** KEYWORDS:
1eb60 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 {SQL statement c
1eb70 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 ompiler}.**.** T
1eb80 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c o execute an SQL
1eb90 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 query, it must
1eba0 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 first be compile
1ebb0 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f d into a byte-co
1ebc0 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 de.** program us
1ebd0 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 ing one of these
1ebe0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a routines..**.**
1ebf0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
1ec00 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 ent, "db", is a
1ec10 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
1ec20 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 tion] obtained f
1ec30 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 rom a.** prior s
1ec40 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 uccessful call t
1ec50 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 o [sqlite3_open(
1ec60 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 )], [sqlite3_ope
1ec70 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 n_v2()] or.** [s
1ec80 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d qlite3_open16()]
1ec90 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 . The database
1eca0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 connection must
1ecb0 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c not have been cl
1ecc0 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 osed..**.** The
1ecd0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c second argument,
1ece0 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 "zSql", is the
1ecf0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 statement to be
1ed00 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 compiled, encode
1ed10 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 d.** as either U
1ed20 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 TF-8 or UTF-16.
1ed30 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 The sqlite3_pre
1ed40 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 pare() and sqlit
1ed50 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a e3_prepare_v2().
1ed60 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 ** interfaces us
1ed70 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c e UTF-8, and sql
1ed80 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
1ed90 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 and sqlite3_pre
1eda0 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 pare16_v2().** u
1edb0 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a se UTF-16..**.**
1edc0 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 ^If the nByte a
1edd0 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 rgument is less
1ede0 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 than zero, then
1edf0 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 zSql is read up
1ee00 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 to the.** first
1ee10 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e zero terminator.
1ee20 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f ^If nByte is no
1ee30 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e n-negative, then
1ee40 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d it is the maxim
1ee50 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 um.** number of
1ee60 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d bytes read from
1ee70 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 zSql. ^When nB
1ee80 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 yte is non-negat
1ee90 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c ive, the.** zSql
1eea0 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 string ends at
1eeb0 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74 either the first
1eec0 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 '\000' or '\u00
1eed0 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 00' character or
1eee0 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 .** the nByte-th
1eef0 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 byte, whichever
1ef00 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 comes first. If
1ef10 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 the caller know
1ef20 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 s.** that the su
1ef30 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 pplied string is
1ef40 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c nul-terminated,
1ef50 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 then there is a
1ef60 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 small.** perfor
1ef70 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 mance advantage
1ef80 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 to be gained by
1ef90 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 passing an nByte
1efa0 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a parameter that.
1efb0 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 ** is equal to t
1efc0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
1efd0 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 es in the input
1efe0 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 string <i>includ
1eff0 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e ing</i>.** the n
1f000 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 ul-terminator by
1f010 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 tes..**.** ^If p
1f020 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c zTail is not NUL
1f030 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 L then *pzTail i
1f040 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 s made to point
1f050 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74 to the first byt
1f060 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e e.** past the en
1f070 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 d of the first S
1f080 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 QL statement in
1f090 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 zSql. These rou
1f0a0 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f tines only.** co
1f0b0 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 mpile the first
1f0c0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 statement in zSq
1f0d0 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 l, so *pzTail is
1f0e0 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 left pointing t
1f0f0 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e o.** what remain
1f100 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a s uncompiled..**
1f110 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 .** ^*ppStmt is
1f120 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f left pointing to
1f130 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 a compiled [pre
1f140 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
1f150 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 that can be.**
1f160 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b executed using [
1f170 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e sqlite3_step()].
1f180 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 ^If there is a
1f190 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 n error, *ppStmt
1f1a0 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 is set.** to NU
1f1b0 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 LL. ^If the inp
1f1c0 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 ut text contains
1f1d0 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 no SQL (if the
1f1e0 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 input is an empt
1f1f0 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 y.** string or a
1f200 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a comment) then *
1f210 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f ppStmt is set to
1f220 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 NULL..** The ca
1f230 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 lling procedure
1f240 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 is responsible f
1f250 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 or deleting the
1f260 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 compiled.** SQL
1f270 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 statement using
1f280 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
1f290 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 e()] after it ha
1f2a0 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 s finished with
1f2b0 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 it..** ppStmt ma
1f2c0 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a y not be NULL..*
1f2d0 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 *.** ^On success
1f2e0 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 , the sqlite3_pr
1f2f0 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f epare() family o
1f300 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 f routines retur
1f310 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a n [SQLITE_OK];.*
1f320 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b * otherwise an [
1f330 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 error code] is r
1f340 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 eturned..**.** T
1f350 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 he sqlite3_prepa
1f360 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 re_v2() and sqli
1f370 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
1f380 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 () interfaces ar
1f390 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 e.** recommended
1f3a0 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f for all new pro
1f3b0 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f grams. The two o
1f3c0 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 lder interfaces
1f3d0 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 are retained.**
1f3e0 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f for backwards co
1f3f0 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 mpatibility, but
1f400 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69 their use is di
1f410 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 scouraged..** ^I
1f420 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 n the "v2" inter
1f430 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 faces, the prepa
1f440 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a red statement.**
1f450 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 that is returne
1f460 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f d (the [sqlite3_
1f470 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f stmt] object) co
1f480 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 ntains a copy of
1f490 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c the.** original
1f4a0 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 SQL text. This
1f4b0 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 causes the [sqli
1f4c0 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 te3_step()] inte
1f4d0 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 rface to.** beha
1f4e0 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 ve differently i
1f4f0 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a n three ways:.**
1f500 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ol>.** <li>
1f510 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 .** ^If the data
1f520 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e base schema chan
1f530 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 ges, instead of
1f540 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 returning [SQLIT
1f550 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a E_SCHEMA] as it.
1f560 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 ** always used t
1f570 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 o do, [sqlite3_s
1f580 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f tep()] will auto
1f590 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 matically recomp
1f5a0 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 ile the SQL.** s
1f5b0 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 tatement and try
1f5c0 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e to run it again
1f5d0 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a ..** </li>.**.**
1f5e0 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 <li>.** ^When a
1f5f0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 n error occurs,
1f600 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
1f610 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 will return one
1f620 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 of the detailed
1f630 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 .** [error codes
1f640 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 ] or [extended e
1f650 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 rror codes]. ^T
1f660 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 he legacy behavi
1f670 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b or was that.** [
1f680 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
1f690 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 would only retur
1f6a0 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c n a generic [SQL
1f6b0 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c ITE_ERROR] resul
1f6c0 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 t code.** and th
1f6d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f e application wo
1f6e0 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 uld have to make
1f6f0 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 a second call t
1f700 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 o [sqlite3_reset
1f710 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 ()].** in order
1f720 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 to find the unde
1f730 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 rlying cause of
1f740 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 the problem. Wit
1f750 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 h the "v2" prepa
1f760 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 re.** interfaces
1f770 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 , the underlying
1f780 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 reason for the
1f790 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 error is returne
1f7a0 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a d immediately..*
1f7b0 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c * </li>.**.** <l
1f7c0 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 i>.** ^If the sp
1f7d0 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 ecific value bou
1f7e0 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 nd to [parameter
1f7f0 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 | host paramete
1f800 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 r] in the .** WH
1f810 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 ERE clause might
1f820 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 influence the c
1f830 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 hoice of query p
1f840 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d lan for a statem
1f850 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ent,.** then the
1f860 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 statement will
1f870 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 be automatically
1f880 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 recompiled, as
1f890 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65 if there had bee
1f8a0 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 n .** a schema c
1f8b0 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 hange, on the fi
1f8c0 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 rst [sqlite3_st
1f8d0 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f ep()] call follo
1f8e0 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a wing any change.
1f8f0 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 ** to the [sqlit
1f900 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 e3_bind_text | b
1f910 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 indings] of that
1f920 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a [parameter]. .*
1f930 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 * ^The specific
1f940 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 value of WHERE-c
1f950 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 lause [parameter
1f960 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 ] might influenc
1f970 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 e the .** choice
1f980 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 of query plan i
1f990 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 f the parameter
1f9a0 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 is the left-hand
1f9b0 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 side of a [LIKE
1f9c0 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f ].** or [GLOB] o
1f9d0 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 perator or if th
1f9e0 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 e parameter is c
1f9f0 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e ompared to an in
1fa00 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 dexed column.**
1fa10 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f and the [SQLITE_
1fa20 45 4e 41 42 4c 45 5f 53 54 41 54 32 5d 20 63 6f ENABLE_STAT2] co
1fa30 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
1fa40 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a n is enabled..**
1fa50 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a the .** </li>.*
1fa60 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 * </ol>.*/.SQLIT
1fa70 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
1fa80 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 3_prepare(. sql
1fa90 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
1faa0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
1fab0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
1fac0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 st char *zSql,
1fad0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 /* SQL stat
1fae0 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 ement, UTF-8 enc
1faf0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 oded */. int nB
1fb00 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 yte,
1fb10 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e /* Maximum len
1fb20 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 gth of zSql in b
1fb30 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 ytes. */. sqlit
1fb40 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 e3_stmt **ppStmt
1fb50 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 , /* OUT: State
1fb60 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 ment handle */.
1fb70 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a const char **pz
1fb80 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a Tail /* OUT:
1fb90 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 Pointer to unus
1fba0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 ed portion of zS
1fbb0 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f ql */.);.SQLITE_
1fbc0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
1fbd0 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 prepare_v2(. sq
1fbe0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
1fbf0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 /* Databas
1fc00 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f e handle */. co
1fc10 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 nst char *zSql,
1fc20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 /* SQL sta
1fc30 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e tement, UTF-8 en
1fc40 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e coded */. int n
1fc50 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 Byte,
1fc60 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 /* Maximum le
1fc70 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 ngth of zSql in
1fc80 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 bytes. */. sqli
1fc90 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d te3_stmt **ppStm
1fca0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 t, /* OUT: Stat
1fcb0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a ement handle */.
1fcc0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 const char **p
1fcd0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 zTail /* OUT
1fce0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 : Pointer to unu
1fcf0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a sed portion of z
1fd00 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 Sql */.);.SQLITE
1fd10 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
1fd20 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 _prepare16(. sq
1fd30 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
1fd40 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 /* Databas
1fd50 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f e handle */. co
1fd60 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 nst void *zSql,
1fd70 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 /* SQL sta
1fd80 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 tement, UTF-16 e
1fd90 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 ncoded */. int
1fda0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 nByte,
1fdb0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c /* Maximum l
1fdc0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e ength of zSql in
1fdd0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c bytes. */. sql
1fde0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 ite3_stmt **ppSt
1fdf0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 mt, /* OUT: Sta
1fe00 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f tement handle */
1fe10 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a . const void **
1fe20 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 pzTail /* OU
1fe30 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e T: Pointer to un
1fe40 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 used portion of
1fe50 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 zSql */.);.SQLIT
1fe60 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
1fe70 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 3_prepare16_v2(.
1fe80 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
1fe90 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 /* Dat
1fea0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a abase handle */.
1feb0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 const void *zS
1fec0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c ql, /* SQL
1fed0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d statement, UTF-
1fee0 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 16 encoded */.
1fef0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 int nByte,
1ff00 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d /* Maxim
1ff10 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 um length of zSq
1ff20 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 l in bytes. */.
1ff30 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a sqlite3_stmt **
1ff40 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a ppStmt, /* OUT:
1ff50 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c Statement handl
1ff60 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 e */. const voi
1ff70 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f d **pzTail /
1ff80 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 * OUT: Pointer t
1ff90 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e o unused portion
1ffa0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a of zSql */.);..
1ffb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1ffc0 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 Retrieving State
1ffd0 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e ment SQL.**.** ^
1ffe0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 This interface c
1fff0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 an be used to re
20000 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63 trieve a saved c
20010 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 opy of the origi
20020 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 nal.** SQL text
20030 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 used to create a
20040 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
20050 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 ment] if that st
20060 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 atement was.** c
20070 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 ompiled using ei
20080 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 ther [sqlite3_pr
20090 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b epare_v2()] or [
200a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
200b0 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 6_v2()]..*/.SQLI
200c0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 TE_API const cha
200d0 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 r *sqlite3_sql(s
200e0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
200f0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
20100 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 3REF: Determine
20110 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d If An SQL Statem
20120 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44 ent Writes The D
20130 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 atabase.**.** ^T
20140 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f he sqlite3_stmt_
20150 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 readonly(X) inte
20160 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 rface returns tr
20170 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 ue (non-zero) if
20180 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 .** and only if
20190 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
201a0 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 atement] X makes
201b0 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 no direct chang
201c0 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e es to.** the con
201d0 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 tent of the data
201e0 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a base file..**.**
201f0 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c Note that [appl
20200 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
20210 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f SQL functions] o
20220 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 r.** [virtual ta
20230 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e bles] might chan
20240 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ge the database
20250 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 indirectly as a
20260 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a side effect. .*
20270 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c * ^(For example,
20280 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 if an applicati
20290 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e on defines a fun
202a0 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 ction "eval()" t
202b0 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 hat .** calls [s
202c0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 qlite3_exec()],
202d0 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 then the followi
202e0 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ng SQL statement
202f0 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 would.** change
20300 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
20310 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d le through side-
20320 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c effects:.**.** <
20330 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
20340 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 .** SELECT ev
20350 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 al('DELETE FROM
20360 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a t1') FROM t2;.**
20370 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 </pre></blockqu
20380 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 ote>.**.** But b
20390 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 ecause the [SELE
203a0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f CT] statement do
203b0 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 es not change th
203c0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a e database file.
203d0 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c ** directly, sql
203e0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e ite3_stmt_readon
203f0 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c ly() would still
20400 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a return true.)^.
20410 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 **.** ^Transacti
20420 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 on control state
20430 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 ments such as [B
20440 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c EGIN], [COMMIT],
20450 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 [ROLLBACK],.**
20460 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 [SAVEPOINT], and
20470 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 [RELEASE] cause
20480 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 sqlite3_stmt_re
20490 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 adonly() to retu
204a0 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 rn true,.** sinc
204b0 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 e the statements
204c0 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e themselves do n
204d0 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 ot actually modi
204e0 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 fy the database
204f0 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 but.** rather th
20500 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 ey control the t
20510 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 iming of when ot
20520 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d her statements m
20530 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 odify the .** da
20540 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 tabase. ^The [A
20550 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 TTACH] and [DETA
20560 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 CH] statements a
20570 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c lso cause.** sql
20580 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e ite3_stmt_readon
20590 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 ly() to return t
205a0 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 rue since, while
205b0 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 those statement
205c0 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 s.** change the
205d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 configuration of
205e0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a database conn
205f0 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 ection, they do
20600 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 not make .** cha
20610 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 nges to the cont
20620 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 ent of the datab
20630 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 ase files on dis
20640 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 k..*/.SQLITE_API
20650 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d int sqlite3_stm
20660 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 t_readonly(sqlit
20670 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b e3_stmt *pStmt);
20680 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
20690 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 : Dynamically Ty
206a0 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 ped Value Object
206b0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 .** KEYWORDS: {p
206c0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
206d0 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 _value} {unprote
206e0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
206f0 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 ue}.**.** SQLite
20700 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 uses the sqlite
20710 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 3_value object t
20720 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 o represent all
20730 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 values.** that c
20740 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 an be stored in
20750 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 a database table
20760 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 . SQLite uses dy
20770 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 namic typing.**
20780 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 for the values i
20790 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 t stores. ^Valu
207a0 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c es stored in sql
207b0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
207c0 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 ts.** can be int
207d0 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 egers, floating
207e0 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 point values, st
207f0 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 rings, BLOBs, or
20800 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 NULL..**.** An
20810 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
20820 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 ject may be eith
20830 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f er "protected" o
20840 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e r "unprotected".
20850 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 .** Some interfa
20860 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 ces require a pr
20870 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
20880 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e value. Other in
20890 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c terfaces.** will
208a0 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 accept either a
208b0 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e protected or an
208c0 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c unprotected sql
208d0 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 ite3_value..** E
208e0 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 very interface t
208f0 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 hat accepts sqli
20900 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 te3_value argume
20910 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a nts specifies.**
20920 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
20930 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 it requires a pr
20940 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
20950 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 value..**.** The
20960 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 terms "protecte
20970 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 d" and "unprotec
20980 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 ted" refer to wh
20990 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 ether or not.**
209a0 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e a mutex is held.
209b0 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 An internal mu
209c0 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 tex is held for
209d0 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 a protected.** s
209e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
209f0 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 ect but no mutex
20a00 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 is held for an
20a10 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 unprotected.** s
20a20 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
20a30 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 ect. If SQLite
20a40 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 is compiled to b
20a50 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 e single-threade
20a60 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 d.** (with [SQLI
20a70 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d TE_THREADSAFE=0]
20a80 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 and with [sqlit
20a90 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d e3_threadsafe()]
20aa0 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a returning 0).**
20ab0 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 or if SQLite is
20ac0 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 run in one of r
20ad0 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 educed mutex mod
20ae0 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 es .** [SQLITE_C
20af0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 ONFIG_SINGLETHRE
20b00 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 AD] or [SQLITE_C
20b10 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 ONFIG_MULTITHREA
20b20 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 D].** then there
20b30 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 is no distincti
20b40 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 on between prote
20b50 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 cted and unprote
20b60 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f cted.** sqlite3_
20b70 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e value objects an
20b80 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 d they can be us
20b90 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 ed interchangeab
20ba0 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a ly. However,.**
20bb0 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 for maximum cod
20bc0 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 e portability it
20bd0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 is recommended
20be0 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e that application
20bf0 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 s.** still make
20c00 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 the distinction
20c10 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 between protecte
20c20 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 d and unprotecte
20c30 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c d.** sqlite3_val
20c40 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 ue objects even
20c50 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c when not strictl
20c60 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a y required..**.*
20c70 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 * ^The sqlite3_v
20c80 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 alue objects tha
20c90 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 t are passed as
20ca0 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 parameters into
20cb0 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 the.** implement
20cc0 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 ation of [applic
20cd0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
20ce0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 L functions] are
20cf0 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e protected..** ^
20d00 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 The sqlite3_valu
20d10 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 e object returne
20d20 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 d by.** [sqlite3
20d30 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d _column_value()]
20d40 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e is unprotected.
20d50 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 .** Unprotected
20d60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
20d70 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 jects may only b
20d80 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b e used with.** [
20d90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 sqlite3_result_v
20da0 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c alue()] and [sql
20db0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 ite3_bind_value(
20dc0 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 )]..** The [sqli
20dd0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c te3_value_blob |
20de0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
20df0 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 ype()] family of
20e00 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 .** interfaces r
20e10 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 equire protected
20e20 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
20e30 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 bjects..*/.typed
20e40 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 ef struct Mem sq
20e50 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a lite3_value;../*
20e60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 .** CAPI3REF: SQ
20e70 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 L Function Conte
20e80 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 xt Object.**.**
20e90 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 The context in w
20ea0 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 hich an SQL func
20eb0 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 tion executes is
20ec0 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a stored in an.**
20ed0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
20ee0 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 object. ^A poi
20ef0 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 nter to an sqlit
20f00 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 e3_context objec
20f10 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 t.** is always f
20f20 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 irst parameter t
20f30 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 o [application-d
20f40 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
20f50 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 ions]..** The ap
20f60 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
20f70 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 d SQL function i
20f80 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 mplementation wi
20f90 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 ll pass this.**
20fa0 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 pointer through
20fb0 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 into calls to [s
20fc0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e qlite3_result_in
20fd0 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 t | sqlite3_resu
20fe0 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 lt()],.** [sqlit
20ff0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
21000 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 text()], [sqlite
21010 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 3_user_data()],.
21020 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ** [sqlite3_cont
21030 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d ext_db_handle()]
21040 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 , [sqlite3_get_a
21050 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e uxdata()],.** an
21060 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 d/or [sqlite3_se
21070 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f t_auxdata()]..*/
21080 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
21090 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 sqlite3_context
210a0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b sqlite3_context;
210b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
210c0 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 : Binding Values
210d0 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 To Prepared Sta
210e0 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f tements.** KEYWO
210f0 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d RDS: {host param
21100 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 eter} {host para
21110 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 meters} {host pa
21120 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a rameter name}.**
21130 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 KEYWORDS: {SQL
21140 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 parameter} {SQL
21150 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 parameters} {par
21160 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a ameter binding}.
21170 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 **.** ^(In the S
21180 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 QL statement tex
21190 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 t input to [sqli
211a0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
211b0 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e ] and its varian
211c0 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 ts,.** literals
211d0 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 may be replaced
211e0 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d by a [parameter]
211f0 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e that matches on
21200 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a e of following.*
21210 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a * templates:.**.
21220 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
21230 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e ?.** <li> ?NNN
21240 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a .** <li> :VVV.*
21250 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 * <li> @VVV.**
21260 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f <li> $VVV.** </
21270 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 ul>.**.** In the
21280 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 templates above
21290 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 , NNN represents
212a0 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 an integer lite
212b0 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 ral,.** and VVV
212c0 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c represents an al
212d0 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 phanumeric ident
212e0 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 ifier.)^ ^The v
212f0 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a alues of these.*
21300 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c * parameters (al
21310 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 so called "host
21320 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 parameter names"
21330 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 or "SQL paramet
21340 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 ers").** can be
21350 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 set using the sq
21360 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 lite3_bind_*() r
21370 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 outines defined
21380 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 here..**.** ^The
21390 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
213a0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 to the sqlite3_b
213b0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 ind_*() routines
213c0 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 is always.** a
213d0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b pointer to the [
213e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 sqlite3_stmt] ob
213f0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 ject returned fr
21400 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 om.** [sqlite3_p
21410 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
21420 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a its variants..**
21430 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 .** ^The second
21440 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 argument is the
21450 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c index of the SQL
21460 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 parameter to be
21470 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 set..** ^The le
21480 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d ftmost SQL param
21490 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 eter has an inde
214a0 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 x of 1. ^When t
214b0 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a he same named.**
214c0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 SQL parameter i
214d0 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e s used more than
214e0 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e once, second an
214f0 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 d subsequent.**
21500 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 occurrences have
21510 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 the same index
21520 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 as the first occ
21530 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 urrence..** ^The
21540 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 index for named
21550 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 parameters can
21560 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 be looked up usi
21570 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 ng the.** [sqlit
21580 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
21590 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 r_index()] API i
215a0 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 f desired. ^The
215b0 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f index.** for "?
215c0 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 NNN" parameters
215d0 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 is the value of
215e0 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e NNN..** ^The NNN
215f0 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 value must be b
21600 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 etween 1 and the
21610 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 [sqlite3_limit(
21620 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 )].** parameter
21630 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 [SQLITE_LIMIT_VA
21640 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 RIABLE_NUMBER] (
21650 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 default value: 9
21660 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 99)..**.** ^The
21670 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 third argument i
21680 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 s the value to b
21690 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d ind to the param
216a0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e eter..**.** ^(In
216b0 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 those routines
216c0 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 that have a four
216d0 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 th argument, its
216e0 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a value is the.**
216f0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
21700 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 in the paramete
21710 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a r. To be clear:
21720 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 the value is th
21730 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c e.** number of <
21740 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 u>bytes</u> in t
21750 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 he value, not th
21760 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 e number of char
21770 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 acters.)^.** ^If
21780 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
21790 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 meter is negativ
217a0 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 e, the length of
217b0 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a the string is.*
217c0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 * the number of
217d0 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 bytes up to the
217e0 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 first zero termi
217f0 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 nator..**.** ^Th
21800 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 e fifth argument
21810 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
21820 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 _blob(), sqlite3
21830 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e _bind_text(), an
21840 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e d.** sqlite3_bin
21850 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20 d_text16() is a
21860 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 destructor used
21870 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 to dispose of th
21880 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 e BLOB or.** str
21890 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 ing after SQLite
218a0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 has finished wi
218b0 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 th it. ^The des
218c0 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 tructor is calle
218d0 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 d.** to dispose
218e0 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 of the BLOB or s
218f0 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 tring even if th
21900 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 e call to sqlite
21910 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 3_bind_blob(),.*
21920 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 * sqlite3_bind_t
21930 65 78 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 ext(), or sqlite
21940 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 3_bind_text16()
21950 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 fails. .** ^If
21960 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 the fifth argume
21970 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 nt is.** the spe
21980 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 cial value [SQLI
21990 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e TE_STATIC], then
219a0 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 SQLite assumes
219b0 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f that the.** info
219c0 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 rmation is in st
219d0 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 atic, unmanaged
219e0 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e space and does n
219f0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 ot need to be fr
21a00 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 eed..** ^If the
21a10 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 fifth argument h
21a20 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 as the value [SQ
21a30 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c LITE_TRANSIENT],
21a40 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 then.** SQLite
21a50 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 makes its own pr
21a60 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 ivate copy of th
21a70 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 e data immediate
21a80 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 ly, before.** th
21a90 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
21aa0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 () routine retur
21ab0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ns..**.** ^The s
21ac0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f qlite3_bind_zero
21ad0 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 blob() routine b
21ae0 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c inds a BLOB of l
21af0 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 ength N that.**
21b00 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a is filled with z
21b10 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 eroes. ^A zerob
21b20 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 lob uses a fixed
21b30 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 amount of memor
21b40 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e y.** (just an in
21b50 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 teger to hold it
21b60 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 s size) while it
21b70 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 is being proces
21b80 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 sed..** Zeroblob
21b90 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 s are intended t
21ba0 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 o serve as place
21bb0 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 holders for BLOB
21bc0 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 s whose.** conte
21bd0 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 nt is later writ
21be0 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 ten using.** [sq
21bf0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 lite3_blob_open
21c00 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c | incremental BL
21c10 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 OB I/O] routines
21c20 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 ..** ^A negative
21c30 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a value for the z
21c40 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 eroblob results
21c50 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 in a zero-length
21c60 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 BLOB..**.** ^If
21c70 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 any of the sqli
21c80 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 te3_bind_*() rou
21c90 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 tines are called
21ca0 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 with a NULL poi
21cb0 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 nter.** for the
21cc0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
21cd0 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 ent] or with a p
21ce0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
21cf0 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b t for which.** [
21d00 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
21d10 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 has been called
21d20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 more recently th
21d30 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 an [sqlite3_rese
21d40 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 t()],.** then th
21d50 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 e call will retu
21d60 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 rn [SQLITE_MISUS
21d70 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 E]. If any sqli
21d80 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 te3_bind_().** r
21d90 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 outine is passed
21da0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
21db0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 tement] that has
21dc0 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c been finalized,
21dd0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 the.** result i
21de0 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 s undefined and
21df0 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c probably harmful
21e00 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 ..**.** ^Binding
21e10 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 s are not cleare
21e20 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 d by the [sqlite
21e30 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 3_reset()] routi
21e40 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 ne..** ^Unbound
21e50 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 parameters are i
21e60 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 nterpreted as NU
21e70 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 LL..**.** ^The s
21e80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f qlite3_bind_* ro
21e90 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 utines return [S
21ea0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 QLITE_OK] on suc
21eb0 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 cess or an.** [e
21ec0 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e rror code] if an
21ed0 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e ything goes wron
21ee0 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 g..** ^[SQLITE_R
21ef0 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 ANGE] is returne
21f00 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 d if the paramet
21f10 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f er.** index is o
21f20 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b ut of range. ^[
21f30 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 SQLITE_NOMEM] is
21f40 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c returned if mal
21f50 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a loc() fails..**.
21f60 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
21f70 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
21f80 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a eter_count()],.*
21f90 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
21fa0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 parameter_name()
21fb0 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ], and [sqlite3_
21fc0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 bind_parameter_i
21fd0 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 ndex()]..*/.SQLI
21fe0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
21ff0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c e3_bind_blob(sql
22000 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
22010 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
22020 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 t n, void(*)(voi
22030 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 d*));.SQLITE_API
22040 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e int sqlite3_bin
22050 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 d_double(sqlite3
22060 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 _stmt*, int, dou
22070 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ble);.SQLITE_API
22080 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e int sqlite3_bin
22090 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 d_int(sqlite3_st
220a0 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a mt*, int, int);.
220b0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
220c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 qlite3_bind_int6
220d0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 4(sqlite3_stmt*,
220e0 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e int, sqlite3_in
220f0 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 t64);.SQLITE_API
22100 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e int sqlite3_bin
22110 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 d_null(sqlite3_s
22120 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 tmt*, int);.SQLI
22130 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
22140 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c e3_bind_text(sql
22150 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
22160 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e const char*, in
22170 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 t n, void(*)(voi
22180 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 d*));.SQLITE_API
22190 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e int sqlite3_bin
221a0 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 d_text16(sqlite3
221b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e _stmt*, int, con
221c0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 st void*, int, v
221d0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
221e0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
221f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 qlite3_bind_valu
22200 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
22210 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 int, const sqli
22220 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c te3_value*);.SQL
22230 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
22240 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f te3_bind_zeroblo
22250 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c b(sqlite3_stmt*,
22260 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f int, int n);../
22270 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e *.** CAPI3REF: N
22280 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 umber Of SQL Par
22290 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 ameters.**.** ^T
222a0 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 his routine can
222b0 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 be used to find
222c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 the number of [S
222d0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a QL parameters].*
222e0 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 * in a [prepared
222f0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 statement]. SQ
22300 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 L parameters are
22310 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a tokens of the.*
22320 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e * form "?", "?NN
22330 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 N", ":AAA", "$AA
22340 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 A", or "@AAA" th
22350 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 at serve as.** p
22360 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 laceholders for
22370 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 values that are
22380 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
22390 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 ob | bound].** t
223a0 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 o the parameters
223b0 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 at a later time
223c0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 ..**.** ^(This r
223d0 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 outine actually
223e0 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 returns the inde
223f0 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 x of the largest
22400 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 (rightmost).**
22410 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 parameter. For a
22420 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 ll forms except
22430 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 ?NNN, this will
22440 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 correspond to th
22450 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 e.** number of u
22460 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 nique parameters
22470 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 . If parameters
22480 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 of the ?NNN for
22490 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 m are used,.** t
224a0 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 here may be gaps
224b0 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a in the list.)^.
224c0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
224d0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
224e0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 ob|sqlite3_bind(
224f0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
22500 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e bind_parameter_n
22510 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b ame()], and.** [
22520 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
22530 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e ameter_index()].
22540 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
22550 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
22560 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 parameter_count(
22570 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a sqlite3_stmt*);.
22580 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
22590 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 Name Of A Host
225a0 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 Parameter.**.**
225b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e ^The sqlite3_bin
225c0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 d_parameter_name
225d0 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 (P,N) interface
225e0 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e returns.** the n
225f0 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 ame of the N-th
22600 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 [SQL parameter]
22610 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 in the [prepared
22620 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a statement] P..*
22630 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 * ^(SQL paramete
22640 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 rs of the form "
22650 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 ?NNN" or ":AAA"
22660 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 or "@AAA" or "$A
22670 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 AA".** have a na
22680 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20 me which is the
22690 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 string "?NNN" or
226a0 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 ":AAA" or "@AAA
226b0 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 " or "$AAA".** r
226c0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 espectively..**
226d0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 In other words,
226e0 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 the initial ":"
226f0 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 or "$" or "@" or
22700 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 "?".** is inclu
22710 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 ded as part of t
22720 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 he name.)^.** ^P
22730 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 arameters of the
22740 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 form "?" withou
22750 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e t a following in
22760 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 teger have no na
22770 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 me.** and are re
22780 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 ferred to as "na
22790 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e meless" or "anon
227a0 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 ymous parameters
227b0 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 "..**.** ^The fi
227c0 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 rst host paramet
227d0 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 er has an index
227e0 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a of 1, not 0..**.
227f0 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 ** ^If the value
22800 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e N is out of ran
22810 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 ge or if the N-t
22820 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a h parameter is.*
22830 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e * nameless, then
22840 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 NULL is returne
22850 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 d. ^The returne
22860 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 d string is.** a
22870 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 lways in UTF-8 e
22880 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 ncoding even if
22890 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 the named parame
228a0 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 ter was.** origi
228b0 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 nally specified
228c0 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 as UTF-16 in [sq
228d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
228e0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 )] or.** [sqlite
228f0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
22900 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 ]..**.** See als
22910 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 o: [sqlite3_bind
22920 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 _blob|sqlite3_bi
22930 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 nd()],.** [sqlit
22940 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
22950 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a r_count()], and.
22960 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
22970 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 _parameter_index
22980 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ()]..*/.SQLITE_A
22990 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 PI const char *s
229a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
229b0 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 meter_name(sqlit
229c0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a e3_stmt*, int);.
229d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
229e0 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 Index Of A Para
229f0 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 meter With A Giv
22a00 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 en Name.**.** ^R
22a10 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 eturn the index
22a20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 of an SQL parame
22a30 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 ter given its na
22a40 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 me. ^The.** ind
22a50 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 ex value returne
22a60 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f d is suitable fo
22a70 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63 r use as the sec
22a80 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ond.** parameter
22a90 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e to [sqlite3_bin
22aa0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 d_blob|sqlite3_b
22ab0 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f ind()]. ^A zero
22ac0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 .** is returned
22ad0 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 if no matching p
22ae0 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e arameter is foun
22af0 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 d. ^The paramet
22b00 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 er.** name must
22b10 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d be given in UTF-
22b20 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 8 even if the or
22b30 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 iginal statement
22b40 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 .** was prepared
22b50 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 from UTF-16 tex
22b60 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
22b70 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
22b80 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
22b90 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f : [sqlite3_bind_
22ba0 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e blob|sqlite3_bin
22bb0 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 d()],.** [sqlite
22bc0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
22bd0 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a _count()], and.*
22be0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
22bf0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 parameter_index(
22c00 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 )]..*/.SQLITE_AP
22c10 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 I int sqlite3_bi
22c20 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 nd_parameter_ind
22c30 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ex(sqlite3_stmt*
22c40 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
22c50 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ame);../*.** CAP
22c60 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c I3REF: Reset All
22c70 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 Bindings On A P
22c80 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e repared Statemen
22c90 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 t.**.** ^Contrar
22ca0 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 y to the intuiti
22cb0 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c on of many, [sql
22cc0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f ite3_reset()] do
22cd0 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 es not reset.**
22ce0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e the [sqlite3_bin
22cf0 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 d_blob | binding
22d00 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 s] on a [prepare
22d10 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a d statement]..**
22d20 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 ^Use this routi
22d30 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 ne to reset all
22d40 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 host parameters
22d50 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 to NULL..*/.SQLI
22d60 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
22d70 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 e3_clear_binding
22d80 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 s(sqlite3_stmt*)
22d90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
22da0 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c F: Number Of Col
22db0 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 umns In A Result
22dc0 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 Set.**.** ^Retu
22dd0 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 rn the number of
22de0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 columns in the
22df0 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 result set retur
22e00 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 ned by the.** [p
22e10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
22e20 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e t]. ^This routin
22e30 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 e returns 0 if p
22e40 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a Stmt is an SQL.*
22e50 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 * statement that
22e60 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e does not return
22e70 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 data (for examp
22e80 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e le an [UPDATE]).
22e90 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
22ea0 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 [sqlite3_data_c
22eb0 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 ount()].*/.SQLIT
22ec0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
22ed0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 3_column_count(s
22ee0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
22ef0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
22f00 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 3REF: Column Nam
22f10 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 es In A Result S
22f20 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 et.**.** ^These
22f30 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
22f40 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 the name assigne
22f50 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 d to a particula
22f60 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 r column.** in t
22f70 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 he result set of
22f80 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 a [SELECT] stat
22f90 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c ement. ^The sql
22fa0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
22fb0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 ().** interface
22fc0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
22fd0 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d r to a zero-term
22fe0 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 inated UTF-8 str
22ff0 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 ing.** and sqlit
23000 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 e3_column_name16
23010 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 () returns a poi
23020 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 nter to a zero-t
23030 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 erminated.** UTF
23040 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 -16 string. ^Th
23050 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
23060 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 r is the [prepar
23070 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a ed statement].**
23080 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 that implements
23090 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 the [SELECT] st
230a0 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 atement. ^The se
230b0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 cond parameter i
230c0 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 s the.** column
230d0 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 number. ^The le
230e0 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 ftmost column is
230f0 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a number 0..**.**
23100 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 ^The returned s
23110 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 tring pointer is
23120 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 valid until eit
23130 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 her the [prepare
23140 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 d statement].**
23150 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 is destroyed by
23160 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
23170 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 e()] or until th
23180 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 e statement is a
23190 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 utomatically.**
231a0 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 reprepared by th
231b0 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 e first call to
231c0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
231d0 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 for a particula
231e0 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 r run.** or unti
231f0 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 l the next call
23200 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f to.** sqlite3_co
23210 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 lumn_name() or s
23220 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
23230 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 me16() on the sa
23240 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a me column..**.**
23250 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c ^If sqlite3_mal
23260 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 loc() fails duri
23270 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e ng the processin
23280 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 g of either rout
23290 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d ine.** (for exam
232a0 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e ple during a con
232b0 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 version from UTF
232c0 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 -8 to UTF-16) th
232d0 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 en a.** NULL poi
232e0 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 nter is returned
232f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d ..**.** ^The nam
23300 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f e of a result co
23310 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 lumn is the valu
23320 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c e of the "AS" cl
23330 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 ause for.** that
23340 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 column, if ther
23350 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 e is an AS claus
23360 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 e. If there is
23370 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 no AS clause.**
23380 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 then the name of
23390 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 the column is u
233a0 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d nspecified and m
233b0 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a ay change from.*
233c0 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 * one release of
233d0 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e SQLite to the n
233e0 65 78 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ext..*/.SQLITE_A
233f0 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 PI const char *s
23400 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
23410 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
23420 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 , int N);.SQLITE
23430 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 _API const void
23440 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
23450 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 name16(sqlite3_s
23460 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f tmt*, int N);../
23470 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
23480 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e ource Of Data In
23490 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a A Query Result.
234a0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 **.** ^These rou
234b0 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 tines provide a
234c0 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 means to determi
234d0 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c ne the database,
234e0 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 table, and.** t
234f0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 able column that
23500 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f is the origin o
23510 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 f a particular r
23520 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a esult column in.
23530 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 ** [SELECT] stat
23540 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e ement..** ^The n
23550 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 ame of the datab
23560 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 ase or table or
23570 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 column can be re
23580 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 turned as.** eit
23590 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 her a UTF-8 or U
235a0 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e TF-16 string. ^
235b0 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 The _database_ r
235c0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a outines return.*
235d0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e * the database n
235e0 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f ame, the _table_
235f0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
23600 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c the table name,
23610 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 and.** the orig
23620 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 in_ routines ret
23630 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e urn the column n
23640 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 ame..** ^The ret
23650 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 urned string is
23660 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 valid until the
23670 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
23680 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 ent] is destroye
23690 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 d.** using [sqli
236a0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
236b0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 or until the sta
236c0 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 tement is automa
236d0 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 tically.** repre
236e0 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 pared by the fir
236f0 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 st call to [sqli
23700 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 te3_step()] for
23710 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e a particular run
23720 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 .** or until the
23730 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f same informatio
23740 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a n is requested.*
23750 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 * again in a dif
23760 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e ferent encoding.
23770 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 .**.** ^The name
23780 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 s returned are t
23790 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 he original un-a
237a0 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 liased names of
237b0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c the.** database,
237c0 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 table, and colu
237d0 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 mn..**.** ^The f
237e0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
237f0 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 these interface
23800 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 s is a [prepared
23810 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 statement]..**
23820 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 ^These functions
23830 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 return informat
23840 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 ion about the Nt
23850 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 h result column
23860 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 returned by.** t
23870 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 he statement, wh
23880 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 ere N is the sec
23890 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 ond function arg
238a0 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c ument..** ^The l
238b0 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 eft-most column
238c0 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 is column 0 for
238d0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a these routines..
238e0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 **.** ^If the Nt
238f0 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 h column returne
23900 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 d by the stateme
23910 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 nt is an express
23920 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 ion or.** subque
23930 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 ry and is not a
23940 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 column value, th
23950 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 en all of these
23960 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e functions return
23970 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 .** NULL. ^Thes
23980 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 e routine might
23990 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c also return NULL
239a0 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c if a memory all
239b0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a ocation error.**
239c0 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 occurs. ^Other
239d0 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 wise, they retur
239e0 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 n the name of th
239f0 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 e attached datab
23a00 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f ase, table,.** o
23a10 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 r column that qu
23a20 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d ery result colum
23a30 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 n was extracted
23a40 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 from..**.** ^As
23a50 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 with all other S
23a60 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 QLite APIs, thos
23a70 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e e whose names en
23a80 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 d with "16" retu
23a90 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 rn.** UTF-16 enc
23aa0 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 oded strings and
23ab0 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 the other funct
23ac0 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d ions return UTF-
23ad0 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 8..**.** ^These
23ae0 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 APIs are only av
23af0 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c ailable if the l
23b00 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 ibrary was compi
23b10 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 led with the.**
23b20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 [SQLITE_ENABLE_C
23b30 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 OLUMN_METADATA]
23b40 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 C-preprocessor s
23b50 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 ymbol..**.** If
23b60 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 two or more thre
23b70 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 ads call one or
23b80 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f more of these ro
23b90 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 utines against t
23ba0 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 he same.** prepa
23bb0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e red statement an
23bc0 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 d column at the
23bd0 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 same time then t
23be0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a he results are.*
23bf0 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a * undefined..**.
23c00 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 ** If two or mor
23c10 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f e threads call o
23c20 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 ne or more.** [s
23c30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 qlite3_column_da
23c40 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f tabase_name | co
23c50 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e lumn metadata in
23c60 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 terfaces].** for
23c70 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 the same [prepa
23c80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 red statement] a
23c90 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e nd result column
23ca0 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 .** at the same
23cb0 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 time then the re
23cc0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 sults are undefi
23cd0 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ned..*/.SQLITE_A
23ce0 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 PI const char *s
23cf0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 qlite3_column_da
23d00 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 tabase_name(sqli
23d10 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
23d20 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
23d30 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 void *sqlite3_c
23d40 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e olumn_database_n
23d50 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ame16(sqlite3_st
23d60 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 mt*,int);.SQLITE
23d70 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 _API const char
23d80 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
23d90 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 table_name(sqlit
23da0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 e3_stmt*,int);.S
23db0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
23dc0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
23dd0 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 lumn_table_name1
23de0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
23df0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 int);.SQLITE_API
23e00 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c const char *sql
23e10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 ite3_column_orig
23e20 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f in_name(sqlite3_
23e30 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 stmt*,int);.SQLI
23e40 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 TE_API const voi
23e50 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
23e60 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 n_origin_name16(
23e70 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
23e80 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
23e90 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 REF: Declared Da
23ea0 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 tatype Of A Quer
23eb0 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e y Result.**.** ^
23ec0 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d (The first param
23ed0 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 eter is a [prepa
23ee0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a red statement]..
23ef0 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 ** If this state
23f00 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 ment is a [SELEC
23f10 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 T] statement and
23f20 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
23f30 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e of the.** return
23f40 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 ed result set of
23f50 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 that [SELECT] i
23f60 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e s a table column
23f70 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 (not an.** expr
23f80 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 ession or subque
23f90 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 ry) then the dec
23fa0 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 lared type of th
23fb0 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d e table.** colum
23fc0 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e n is returned.)^
23fd0 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f ^If the Nth co
23fe0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 lumn of the resu
23ff0 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 lt set is an.**
24000 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 expression or su
24010 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e bquery, then a N
24020 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 ULL pointer is r
24030 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 eturned..** ^The
24040 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 returned string
24050 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 is always UTF-8
24060 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 encoded..**.**
24070 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 ^(For example, g
24080 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 iven the databas
24090 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 e schema:.**.**
240a0 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 CREATE TABLE t1(
240b0 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a c1 VARIANT);.**.
240c0 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f ** and the follo
240d0 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 wing statement t
240e0 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a o be compiled:.*
240f0 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b *.** SELECT c1 +
24100 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 1, c1 FROM t1;.
24110 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 **.** this routi
24120 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 ne would return
24130 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 the string "VARI
24140 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 ANT" for the sec
24150 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f ond result.** co
24160 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 lumn (i==1), and
24170 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
24180 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 for the first re
24190 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d sult column (i==
241a0 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 0).)^.**.** ^SQL
241b0 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 ite uses dynamic
241c0 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 run-time typing
241d0 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 . ^So just beca
241e0 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 use a column.**
241f0 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 is declared to c
24200 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 ontain a particu
24210 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f lar type does no
24220 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a t mean that the.
24230 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 ** data stored i
24240 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 n that column is
24250 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 of the declared
24260 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 type. SQLite i
24270 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 s.** strongly ty
24280 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 ped, but the typ
24290 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e ing is dynamic n
242a0 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 ot static. ^Typ
242b0 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 e.** is associat
242c0 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 ed with individu
242d0 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 al values, not w
242e0 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 ith the containe
242f0 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f rs.** used to ho
24300 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e ld those values.
24310 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 .*/.SQLITE_API c
24320 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
24330 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 e3_column_declty
24340 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a pe(sqlite3_stmt*
24350 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 ,int);.SQLITE_AP
24360 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 I const void *sq
24370 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 lite3_column_dec
24380 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f ltype16(sqlite3_
24390 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a stmt*,int);../*.
243a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 ** CAPI3REF: Eva
243b0 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 luate An SQL Sta
243c0 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 tement.**.** Aft
243d0 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 er a [prepared s
243e0 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 tatement] has be
243f0 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e en prepared usin
24400 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c g either.** [sql
24410 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
24420 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 )] or [sqlite3_p
24430 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f repare16_v2()] o
24440 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 r one of the leg
24450 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 acy.** interface
24460 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 s [sqlite3_prepa
24470 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 re()] or [sqlite
24480 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 3_prepare16()],
24490 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a this function.**
244a0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 must be called
244b0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 one or more time
244c0 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 s to evaluate th
244d0 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a e statement..**.
244e0 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f ** The details o
244f0 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f f the behavior o
24500 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 f the sqlite3_st
24510 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 ep() interface d
24520 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 epend.** on whet
24530 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e her the statemen
24540 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75 t was prepared u
24550 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 sing the newer "
24560 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a v2" interface.**
24570 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
24580 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c e_v2()] and [sql
24590 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
245a0 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 2()] or the olde
245b0 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 r legacy.** inte
245c0 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 rface [sqlite3_p
245d0 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 repare()] and [s
245e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
245f0 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 ()]. The use of
24600 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 the.** new "v2"
24610 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 interface is re
24620 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 commended for ne
24630 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 w applications b
24640 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a ut the legacy.**
24650 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 interface will
24660 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 continue to be s
24670 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 upported..**.**
24680 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 ^In the legacy i
24690 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 nterface, the re
246a0 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 turn value will
246b0 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 be either [SQLIT
246c0 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c E_BUSY],.** [SQL
246d0 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 ITE_DONE], [SQLI
246e0 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 TE_ROW], [SQLITE
246f0 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c _ERROR], or [SQL
24700 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 ITE_MISUSE]..**
24710 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 ^With the "v2" i
24720 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 nterface, any of
24730 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 the other [resu
24740 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 lt codes] or.**
24750 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
24760 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 codes] might be
24770 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c returned as wel
24780 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 l..**.** ^[SQLIT
24790 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 E_BUSY] means th
247a0 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 at the database
247b0 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c engine was unabl
247c0 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 e to acquire the
247d0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 .** database loc
247e0 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 ks it needs to d
247f0 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 o its job. ^If
24800 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 the statement is
24810 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f a [COMMIT].** o
24820 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 r occurs outside
24830 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 of an explicit
24840 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 transaction, the
24850 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 n you can retry
24860 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 the.** statement
24870 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d . If the statem
24880 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f ent is not a [CO
24890 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 MMIT] and occurs
248a0 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 within a.** exp
248b0 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f licit transactio
248c0 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c n then you shoul
248d0 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 d rollback the t
248e0 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 ransaction befor
248f0 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e e.** continuing.
24900 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f .**.** ^[SQLITE_
24910 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 DONE] means that
24920 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 the statement h
24930 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 as finished exec
24940 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 uting.** success
24950 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f fully. sqlite3_
24960 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f step() should no
24970 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 t be called agai
24980 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 n on this virtua
24990 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 l.** machine wit
249a0 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 hout first calli
249b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ng [sqlite3_rese
249c0 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 t()] to reset th
249d0 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 e virtual.** mac
249e0 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 hine back to its
249f0 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a initial state..
24a00 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 **.** ^If the SQ
24a10 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e L statement bein
24a20 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 g executed retur
24a30 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 ns any data, the
24a40 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a n [SQLITE_ROW].*
24a50 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 * is returned ea
24a60 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f ch time a new ro
24a70 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 w of data is rea
24a80 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e dy for processin
24a90 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c g by the.** call
24aa0 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d er. The values m
24ab0 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75 ay be accessed u
24ac0 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e sing the [column
24ad0 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e access function
24ae0 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 s]..** sqlite3_s
24af0 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 tep() is called
24b00 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 again to retriev
24b10 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f e the next row o
24b20 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b f data..**.** ^[
24b30 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 SQLITE_ERROR] me
24b40 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 ans that a run-t
24b50 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 ime error (such
24b60 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a as a constraint.
24b70 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 ** violation) ha
24b80 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c s occurred. sql
24b90 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 ite3_step() shou
24ba0 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 ld not be called
24bb0 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 again on.** the
24bc0 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d VM. More inform
24bd0 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 ation may be fou
24be0 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 nd by calling [s
24bf0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d qlite3_errmsg()]
24c00 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c ..** ^With the l
24c10 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c egacy interface,
24c20 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 a more specific
24c30 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 error code (for
24c40 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 example,.** [SQ
24c50 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c LITE_INTERRUPT],
24c60 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d [SQLITE_SCHEMA]
24c70 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 , [SQLITE_CORRUP
24c80 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 T], and so forth
24c90 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 ).** can be obta
24ca0 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 ined by calling
24cb0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
24cc0 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 ] on the.** [pre
24cd0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
24ce0 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 . ^In the "v2"
24cf0 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 interface,.** th
24d00 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 e more specific
24d10 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 error code is re
24d20 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 turned directly
24d30 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 by sqlite3_step(
24d40 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 )..**.** [SQLITE
24d50 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 _MISUSE] means t
24d60 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 hat the this rou
24d70 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 tine was called
24d80 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e inappropriately.
24d90 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 .** Perhaps it w
24da0 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b as called on a [
24db0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
24dc0 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 nt] that has.**
24dd0 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 already been [sq
24de0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c lite3_finalize |
24df0 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f finalized] or o
24e00 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a n one that had.*
24e10 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 * previously ret
24e20 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 urned [SQLITE_ER
24e30 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f ROR] or [SQLITE_
24e40 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f DONE]. Or it co
24e50 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 uld.** be the ca
24e60 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 se that the same
24e70 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
24e80 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 tion is being us
24e90 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 ed by two or.**
24ea0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20 more threads at
24eb0 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 the same moment
24ec0 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 in time..**.** F
24ed0 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 or all versions
24ee0 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 of SQLite up to
24ef0 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e and including 3.
24f00 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6.23.1, a call t
24f10 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 o.** [sqlite3_re
24f20 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 set()] was requi
24f30 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 red after sqlite
24f40 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 3_step() returne
24f50 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 d anything.** ot
24f60 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 her than [SQLITE
24f70 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 _ROW] before any
24f80 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f subsequent invo
24f90 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c cation of.** sql
24fa0 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 ite3_step(). Fa
24fb0 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 ilure to reset t
24fc0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 he prepared stat
24fd0 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 ement using .**
24fe0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
24ff0 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 ] would result i
25000 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 n an [SQLITE_MIS
25010 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d USE] return from
25020 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 .** sqlite3_step
25030 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 (). But after v
25040 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c ersion 3.6.23.1,
25050 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
25060 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 began.** calling
25070 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
25080 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 )] automatically
25090 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 in this circums
250a0 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 tance rather.**
250b0 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b than returning [
250c0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 SQLITE_MISUSE].
250d0 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e This is not con
250e0 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 sidered a compat
250f0 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b ibility.** break
25100 20 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 because any app
25110 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 lication that ev
25120 65 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 er receives an S
25130 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 QLITE_MISUSE err
25140 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 or.** is broken
25150 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 by definition.
25160 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 The [SQLITE_OMIT
25170 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 _AUTORESET] comp
25180 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a ile-time option.
25190 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 ** can be used t
251a0 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 o restore the le
251b0 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a gacy behavior..*
251c0 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e *.** <b>Goofy In
251d0 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f terface Alert:</
251e0 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 b> In the legacy
251f0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 interface, the
25200 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a sqlite3_step().*
25210 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 * API always ret
25220 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 urns a generic e
25230 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 rror code, [SQLI
25240 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f TE_ERROR], follo
25250 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f wing any.** erro
25260 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 r other than [SQ
25270 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b LITE_BUSY] and [
25280 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 SQLITE_MISUSE].
25290 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a You must call.*
252a0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 * [sqlite3_reset
252b0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
252c0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f finalize()] in o
252d0 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 rder to find one
252e0 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 of the.** speci
252f0 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 fic [error codes
25300 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 ] that better de
25310 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f scribes the erro
25320 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 r..** We admit t
25330 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f hat this is a go
25340 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 ofy design. The
25350 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 problem has bee
25360 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 n fixed.** with
25370 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
25380 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 ce. If you prep
25390 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 are all of your
253a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a SQL statements.*
253b0 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b * using either [
253c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
253d0 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 v2()] or [sqlite
253e0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
253f0 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 ] instead.** of
25400 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 the legacy [sqli
25410 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 te3_prepare()] a
25420 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 nd [sqlite3_prep
25430 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 are16()] interfa
25440 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ces,.** then the
25450 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b more specific [
25460 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 error codes] are
25470 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 returned direct
25480 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 ly.** by sqlite3
25490 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 _step(). The us
254a0 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e e of the "v2" in
254b0 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d terface is recom
254c0 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 mended..*/.SQLIT
254d0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
254e0 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 3_step(sqlite3_s
254f0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 tmt*);../*.** CA
25500 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f PI3REF: Number o
25510 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 f columns in a r
25520 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 esult set.**.**
25530 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 ^The sqlite3_dat
25540 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 a_count(P) inter
25550 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 face returns the
25560 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
25570 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 ns in the.** cur
25580 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 rent row of the
25590 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 result set of [p
255a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
255b0 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 t] P..** ^If pre
255c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
255d0 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 P does not have
255e0 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f results ready to
255f0 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 return.** (via
25600 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 calls to the [sq
25610 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 lite3_column_int
25620 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d | sqlite3_colum
25630 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 n_*()] of.** int
25640 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 erfaces) then sq
25650 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 lite3_data_count
25660 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a (P) returns 0..*
25670 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 * ^The sqlite3_d
25680 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 ata_count(P) rou
25690 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e tine also return
256a0 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 s 0 if P is a NU
256b0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
256c0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
256d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e ite3_column_coun
256e0 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 t()].*/.SQLITE_A
256f0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 PI int sqlite3_d
25700 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 ata_count(sqlite
25710 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 3_stmt *pStmt);.
25720 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
25730 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 Fundamental Dat
25740 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 atypes.** KEYWOR
25750 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a DS: SQLITE_TEXT.
25760 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 **.** ^(Every va
25770 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 lue in SQLite ha
25780 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 s one of five fu
25790 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 ndamental dataty
257a0 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a pes:.**.** <ul>.
257b0 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 ** <li> 64-bit s
257c0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a igned integer.**
257d0 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 <li> 64-bit IEE
257e0 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 E floating point
257f0 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 number.** <li>
25800 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 string.** <li> B
25810 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c LOB.** <li> NULL
25820 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a .** </ul>)^.**.*
25830 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 * These constant
25840 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 s are codes for
25850 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 each of those ty
25860 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 pes..**.** Note
25870 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f that the SQLITE_
25880 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 TEXT constant wa
25890 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 s also used in S
258a0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a QLite version 2.
258b0 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 ** for a complet
258c0 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 ely different me
258d0 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 aning. Software
258e0 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 that links agai
258f0 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 nst both.** SQLi
25900 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 te version 2 and
25910 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
25920 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 3 should use SQL
25930 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a ITE3_TEXT, not.*
25940 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a * SQLITE_TEXT..*
25950 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
25960 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 _INTEGER 1.#def
25970 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 ine SQLITE_FLOAT
25980 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 2.#define SQ
25990 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a LITE_BLOB 4.
259a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e #define SQLITE_N
259b0 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 ULL 5.#ifdef
259c0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 SQLITE_TEXT.# u
259d0 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 ndef SQLITE_TEXT
259e0 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 .#else.# define
259f0 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 SQLITE_TEXT
25a00 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 3.#endif.#define
25a10 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 SQLITE3_TEXT
25a20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 3../*.** CAPI3
25a30 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 REF: Result Valu
25a40 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a es From A Query.
25a50 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f ** KEYWORDS: {co
25a60 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 lumn access func
25a70 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 tions}.**.** The
25a80 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d se routines form
25a90 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 the "result set
25aa0 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a " interface..**.
25ab0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e ** ^These routin
25ac0 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d es return inform
25ad0 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 ation about a si
25ae0 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 ngle column of t
25af0 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 he current.** re
25b00 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 sult row of a qu
25b10 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 ery. ^In every
25b20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61 case the first a
25b30 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 rgument is a poi
25b40 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b nter.** to the [
25b50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
25b60 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e nt] that is bein
25b70 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 g evaluated (the
25b80 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d [sqlite3_stmt*]
25b90 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 .** that was ret
25ba0 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 urned from [sqli
25bb0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
25bc0 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 ] or one of its
25bd0 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 variants).** and
25be0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
25bf0 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 ment is the inde
25c00 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 x of the column
25c10 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d for which inform
25c20 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 ation.** should
25c30 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 be returned. ^Th
25c40 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d e leftmost colum
25c50 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 n of the result
25c60 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 set has the inde
25c70 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d x 0..** ^The num
25c80 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 ber of columns i
25c90 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e n the result can
25ca0 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 be determined u
25cb0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 sing.** [sqlite3
25cc0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d _column_count()]
25cd0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 ..**.** If the S
25ce0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 QL statement doe
25cf0 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 s not currently
25d00 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 point to a valid
25d10 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a row, or if the.
25d20 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 ** column index
25d30 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c is out of range,
25d40 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 the result is u
25d50 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 ndefined..** The
25d60 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 se routines may
25d70 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 only be called w
25d80 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 hen the most rec
25d90 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b ent call to.** [
25da0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
25db0 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 has returned [SQ
25dc0 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 LITE_ROW] and ne
25dd0 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 ither.** [sqlite
25de0 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 3_reset()] nor [
25df0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
25e00 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 ()] have been ca
25e10 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c lled subsequentl
25e20 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 y..** If any of
25e30 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 these routines a
25e40 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 re called after
25e50 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
25e60 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ] or.** [sqlite3
25e70 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 _finalize()] or
25e80 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 after [sqlite3_s
25e90 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 tep()] has retur
25ea0 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 ned.** something
25eb0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c other than [SQL
25ec0 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 ITE_ROW], the re
25ed0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 sults are undefi
25ee0 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 ned..** If [sqli
25ef0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b te3_step()] or [
25f00 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
25f10 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e or [sqlite3_fin
25f20 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 alize()].** are
25f30 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 called from a di
25f40 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 fferent thread w
25f50 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 hile any of thes
25f60 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 e routines.** ar
25f70 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 e pending, then
25f80 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 the results are
25f90 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
25fa0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f ^The sqlite3_co
25fb0 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 lumn_type() rout
25fc0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a ine returns the.
25fd0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 ** [SQLITE_INTEG
25fe0 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f ER | datatype co
25ff0 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 de] for the init
26000 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a ial data type.**
26010 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 of the result c
26020 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 olumn. ^The ret
26030 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f urned value is o
26040 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e ne of [SQLITE_IN
26050 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 TEGER],.** [SQLI
26060 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 TE_FLOAT], [SQLI
26070 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 TE_TEXT], [SQLIT
26080 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c E_BLOB], or [SQL
26090 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 ITE_NULL]. The
260a0 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 value.** returne
260b0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c d by sqlite3_col
260c0 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e umn_type() is on
260d0 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 ly meaningful if
260e0 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 no type.** conv
260f0 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 ersions have occ
26100 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62 urred as describ
26110 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 ed below. After
26120 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 a type conversi
26130 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 on,.** the value
26140 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
26150 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 ite3_column_type
26160 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e () is undefined.
26170 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 Future.** vers
26180 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d ions of SQLite m
26190 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 ay change the be
261a0 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 havior of sqlite
261b0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 3_column_type().
261c0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 ** following a t
261d0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a ype conversion..
261e0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 **.** ^If the re
261f0 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f sult is a BLOB o
26200 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 r UTF-8 string t
26210 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f hen the sqlite3_
26220 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a column_bytes().*
26230 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e * routine return
26240 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
26250 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c bytes in that BL
26260 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a OB or string..**
26270 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 ^If the result
26280 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 is a UTF-16 stri
26290 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 ng, then sqlite3
262a0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 _column_bytes()
262b0 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 converts.** the
262c0 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 string to UTF-8
262d0 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 and then returns
262e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
262f0 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 ytes..** ^If the
26300 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d result is a num
26310 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 eric value then
26320 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
26330 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b ytes() uses.** [
26340 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
26350 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 ()] to convert t
26360 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 hat value to a U
26370 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 TF-8 string and
26380 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e returns.** the n
26390 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 umber of bytes i
263a0 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a n that string..*
263b0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 * ^If the result
263c0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 is NULL, then s
263d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
263e0 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 tes() returns ze
263f0 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 ro..**.** ^If th
26400 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c e result is a BL
26410 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 OB or UTF-16 str
26420 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c ing then the sql
26430 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
26440 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 s16().** routine
26450 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
26460 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 ber of bytes in
26470 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 that BLOB or str
26480 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ing..** ^If the
26490 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d result is a UTF-
264a0 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 8 string, then s
264b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
264c0 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 tes16() converts
264d0 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 .** the string t
264e0 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 o UTF-16 and the
264f0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 n returns the nu
26500 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a mber of bytes..*
26510 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 * ^If the result
26520 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 is a numeric va
26530 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 lue then sqlite3
26540 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
26550 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 ) uses.** [sqlit
26560 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 e3_snprintf()] t
26570 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 o convert that v
26580 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 alue to a UTF-16
26590 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 string and retu
265a0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 rns.** the numbe
265b0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
265c0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 at string..** ^I
265d0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 f the result is
265e0 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 NULL, then sqlit
265f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
26600 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 6() returns zero
26610 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c ..**.** ^The val
26620 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 ues returned by
26630 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
26640 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a bytes()] and .**
26650 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
26660 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e _bytes16()] do n
26670 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a ot include the z
26680 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 ero terminators
26690 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 at the end.** of
266a0 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 the string. ^F
266b0 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 or clarity: the
266c0 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 values returned
266d0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 by.** [sqlite3_c
266e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 olumn_bytes()] a
266f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 nd [sqlite3_colu
26700 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 mn_bytes16()] ar
26710 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a e the number of.
26720 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 ** bytes in the
26730 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 string, not the
26740 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 number of charac
26750 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 ters..**.** ^Str
26760 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 ings returned by
26770 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
26780 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 text() and sqlit
26790 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
267a0 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 (),.** even empt
267b0 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 y strings, are a
267c0 6c 77 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 lways zero termi
267d0 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 nated. ^The ret
267e0 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f urn.** value fro
267f0 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e m sqlite3_column
26800 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 _blob() for a ze
26810 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 ro-length BLOB i
26820 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
26830 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a ..**.** ^The obj
26840 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 ect returned by
26850 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
26860 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a value()] is an.*
26870 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 * [unprotected s
26880 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
26890 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 ject. An unprot
268a0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
268b0 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 lue object.** ma
268c0 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 y only be used w
268d0 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e ith [sqlite3_bin
268e0 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b d_value()] and [
268f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 sqlite3_result_v
26900 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 alue()]..** If t
26910 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 he [unprotected
26920 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
26930 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 bject returned b
26940 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f y.** [sqlite3_co
26950 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 lumn_value()] is
26960 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 used in any oth
26970 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e er way, includin
26980 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f g calls.** to ro
26990 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c utines like [sql
269a0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 ite3_value_int()
269b0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ], [sqlite3_valu
269c0 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 e_text()],.** or
269d0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
269e0 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 bytes()], then t
269f0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 he behavior is u
26a00 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
26a10 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
26a20 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 ttempt to conver
26a30 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 t the value wher
26a40 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 e appropriate.
26a50 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c ^For.** example,
26a60 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c if the internal
26a70 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 representation
26a80 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 is FLOAT and a t
26a90 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 ext result.** is
26aa0 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c requested, [sql
26ab0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d ite3_snprintf()]
26ac0 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 is used interna
26ad0 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 lly to perform t
26ae0 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e he.** conversion
26af0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 automatically.
26b00 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 ^(The following
26b10 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 table details t
26b20 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a he conversions.*
26b30 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 * that are appli
26b40 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b ed:.**.** <block
26b50 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 quote>.** <table
26b60 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 border="1">.**
26b70 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 <tr><th> Interna
26b80 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 l<br>Type <th> R
26b90 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 equested<br>Type
26ba0 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f <th> Conversio
26bb0 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e n.**.** <tr><td>
26bc0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 NULL <td> I
26bd0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 NTEGER <td> Re
26be0 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 sult is 0.** <tr
26bf0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c ><td> NULL <
26c00 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 td> FLOAT <t
26c10 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 d> Result is 0.0
26c20 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 .** <tr><td> NU
26c30 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 LL <td> TEX
26c40 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 T <td> Result
26c50 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 is NULL pointer
26c60 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 .** <tr><td> NU
26c70 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f LL <td> BLO
26c80 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 B <td> Result
26c90 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 is NULL pointer
26ca0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 .** <tr><td> INT
26cb0 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 EGER <td> FLOA
26cc0 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 T <td> Conver
26cd0 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 t from integer t
26ce0 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c o float.** <tr><
26cf0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 td> INTEGER <td
26d00 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e > TEXT <td>
26d10 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 ASCII rendering
26d20 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a of the integer.
26d30 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 ** <tr><td> INTE
26d40 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 GER <td> BLOB
26d50 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 <td> Same as
26d60 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a INTEGER->TEXT.*
26d70 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 * <tr><td> FLOA
26d80 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 T <td> INTEGER
26d90 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 <td> Convert
26da0 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e from float to in
26db0 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 teger.** <tr><td
26dc0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 > FLOAT <td>
26dd0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 TEXT <td> A
26de0 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f SCII rendering o
26df0 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c f the float.** <
26e00 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 tr><td> FLOAT
26e10 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 <td> BLOB
26e20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f <td> Same as FLO
26e30 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e AT->TEXT.** <tr>
26e40 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 <td> TEXT <t
26e50 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 d> INTEGER <td
26e60 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 > Use atoi().**
26e70 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 <tr><td> TEXT
26e80 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 <td> FLOAT
26e90 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 <td> Use atof()
26ea0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 .** <tr><td> TE
26eb0 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f XT <td> BLO
26ec0 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 B <td> No cha
26ed0 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 nge.** <tr><td>
26ee0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e BLOB <td> IN
26ef0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e TEGER <td> Con
26f00 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 vert to TEXT the
26f10 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 n use atoi().**
26f20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 <tr><td> BLOB
26f30 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 <td> FLOAT
26f40 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f <td> Convert to
26f50 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 TEXT then use a
26f60 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 tof().** <tr><td
26f70 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 > BLOB <td>
26f80 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 TEXT <td> A
26f90 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e dd a zero termin
26fa0 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a ator if needed.*
26fb0 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f * </table>.** </
26fc0 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a blockquote>)^.**
26fd0 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 .** The table ab
26fe0 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 ove makes refere
26ff0 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 nce to standard
27000 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 C library functi
27010 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e ons atoi().** an
27020 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 d atof(). SQLit
27030 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c e does not reall
27040 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 y use these func
27050 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 tions. It has i
27060 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 ts.** own equiva
27070 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f lent internal ro
27080 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f utines. The ato
27090 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e i() and atof() n
270a0 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 ames are.** used
270b0 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f in the table fo
270c0 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 r brevity and be
270d0 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66 cause they are f
270e0 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a amiliar to most.
270f0 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 ** C programmers
27100 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ..**.** Note tha
27110 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 t when type conv
27120 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 ersions occur, p
27130 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 ointers returned
27140 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c by prior.** cal
27150 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ls to sqlite3_co
27160 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c lumn_blob(), sql
27170 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
27180 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 (), and/or.** sq
27190 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
271a0 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 t16() may be inv
271b0 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 alidated..** Typ
271c0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e e conversions an
271d0 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 d pointer invali
271e0 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 dations might oc
271f0 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f cur.** in the fo
27200 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a llowing cases:.*
27210 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
27220 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f > The initial co
27230 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 ntent is a BLOB
27240 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 and sqlite3_colu
27250 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 mn_text() or.**
27260 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c sqlite3_col
27270 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 umn_text16() is
27280 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d called. A zero-
27290 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 terminator might
272a0 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f .** need to
272b0 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 be added to the
272c0 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a string.</li>.**
272d0 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 <li> The initia
272e0 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 l content is UTF
272f0 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 -8 text and sqli
27300 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
27310 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 16() or.**
27320 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
27330 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 ext16() is calle
27340 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 d. The content
27350 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 must be converte
27360 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 d.** to UTF
27370 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 -16.</li>.** <li
27380 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f > The initial co
27390 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 ntent is UTF-16
273a0 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 text and sqlite3
273b0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 _column_bytes()
273c0 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 or.** sqlit
273d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
273e0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 is called. The
273f0 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 content must be
27400 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 converted.**
27410 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 to UTF-8.</li
27420 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a >.** </ul>.**.**
27430 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 ^Conversions be
27440 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 tween UTF-16be a
27450 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 nd UTF-16le are
27460 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 always done in p
27470 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e lace and do.** n
27480 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 ot invalidate a
27490 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 prior pointer, t
274a0 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 hough of course
274b0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 the content of t
274c0 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 he buffer.** tha
274d0 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e t the prior poin
274e0 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 ter references w
274f0 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f ill have been mo
27500 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b dified. Other k
27510 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 inds.** of conve
27520 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 rsion are done i
27530 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 n place when it
27540 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 is possible, but
27550 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a sometimes they.
27560 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 ** are not possi
27570 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 ble and in those
27580 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 cases prior poi
27590 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 nters are invali
275a0 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 dated..**.** The
275b0 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 safest and easi
275c0 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 est to remember
275d0 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 policy is to inv
275e0 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e oke these routin
275f0 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 es.** in one of
27600 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 the following wa
27610 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a ys:.**.** <ul>.*
27620 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 * <li>sqlite3_c
27630 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c olumn_text() fol
27640 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 lowed by sqlite3
27650 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c _column_bytes()<
27660 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c /li>.** <li>sql
27670 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 ite3_column_blob
27680 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 () followed by s
27690 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
276a0 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c tes()</li>.** <
276b0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d li>sqlite3_colum
276c0 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f n_text16() follo
276d0 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 wed by sqlite3_c
276e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c olumn_bytes16()<
276f0 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a /li>.** </ul>.**
27700 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 .** In other wor
27710 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 ds, you should c
27720 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 all sqlite3_colu
27730 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 mn_text(),.** sq
27740 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
27750 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f b(), or sqlite3_
27760 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 column_text16()
27770 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 first to force t
27780 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 he result.** int
27790 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f o the desired fo
277a0 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b rmat, then invok
277b0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
277c0 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 _bytes() or.** s
277d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
277e0 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 tes16() to find
277f0 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
27800 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 result. Do not
27810 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 mix calls.** to
27820 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
27830 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 ext() or sqlite3
27840 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 _column_blob() w
27850 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 ith calls to.**
27860 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
27870 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f ytes16(), and do
27880 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 not mix calls t
27890 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e o sqlite3_column
278a0 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 _text16().** wit
278b0 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 h calls to sqlit
278c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
278d0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f )..**.** ^The po
278e0 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 inters returned
278f0 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 are valid until
27900 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f a type conversio
27910 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 n occurs as.** d
27920 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 escribed above,
27930 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 or until [sqlite
27940 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 3_step()] or [sq
27950 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f lite3_reset()] o
27960 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 r.** [sqlite3_fi
27970 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c nalize()] is cal
27980 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 led. ^The memor
27990 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 y space used to
279a0 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 hold strings.**
279b0 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 and BLOBs is fre
279c0 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ed automatically
279d0 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e . Do <b>not</b>
279e0 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 pass the pointe
279f0 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b rs returned.** [
27a00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
27a10 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 lob()], [sqlite3
27a20 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c _column_text()],
27a30 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 etc. into.** [s
27a40 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a qlite3_free()]..
27a50 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d **.** ^(If a mem
27a60 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 ory allocation e
27a70 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 rror occurs duri
27a80 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f ng the evaluatio
27a90 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 n of any.** of t
27aa0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 hese routines, a
27ab0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 default value i
27ac0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 s returned. The
27ad0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a default value.*
27ae0 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 * is either the
27af0 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 integer 0, the f
27b00 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 loating point nu
27b10 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e mber 0.0, or a N
27b20 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 ULL.** pointer.
27b30 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c Subsequent call
27b40 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 s to [sqlite3_er
27b50 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 rcode()] will re
27b60 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f turn.** [SQLITE_
27b70 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c NOMEM].)^.*/.SQL
27b80 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f ITE_API const vo
27b90 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 id *sqlite3_colu
27ba0 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f mn_blob(sqlite3_
27bb0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
27bc0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
27bd0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
27be0 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 bytes(sqlite3_st
27bf0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
27c00 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
27c10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
27c20 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 tes16(sqlite3_st
27c30 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
27c40 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c SQLITE_API doubl
27c50 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
27c60 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f _double(sqlite3_
27c70 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
27c80 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
27c90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
27ca0 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 int(sqlite3_stmt
27cb0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 *, int iCol);.SQ
27cc0 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 LITE_API sqlite3
27cd0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 _int64 sqlite3_c
27ce0 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 olumn_int64(sqli
27cf0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
27d00 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 Col);.SQLITE_API
27d10 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 const unsigned
27d20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
27d30 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 lumn_text(sqlite
27d40 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
27d50 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 l);.SQLITE_API c
27d60 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
27d70 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
27d80 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
27d90 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 int iCol);.SQLIT
27da0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
27db0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 3_column_type(sq
27dc0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
27dd0 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 iCol);.SQLITE_A
27de0 50 49 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 PI sqlite3_value
27df0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
27e00 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 _value(sqlite3_s
27e10 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
27e20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
27e30 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 : Destroy A Prep
27e40 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f ared Statement O
27e50 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 bject.**.** ^The
27e60 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a sqlite3_finaliz
27e70 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 e() function is
27e80 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 called to delete
27e90 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
27ea0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 tement]..** ^If
27eb0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
27ec0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 evaluation of th
27ed0 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f e statement enco
27ee0 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 untered no error
27ef0 73 20 6f 72 0a 2a 2a 20 6f 72 20 69 66 20 74 68 s or.** or if th
27f00 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e e statement is n
27f10 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 ever been evalua
27f20 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 ted, then sqlite
27f30 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 3_finalize() ret
27f40 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f urns.** SQLITE_O
27f50 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 K. ^If the most
27f60 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 recent evaluati
27f70 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 on of statement
27f80 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a S failed, then.*
27f90 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 * sqlite3_finali
27fa0 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 ze(S) returns th
27fb0 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 e appropriate [e
27fc0 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a rror code] or.**
27fd0 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 [extended error
27fe0 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 code]..**.** ^T
27ff0 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c he sqlite3_final
28000 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 ize(S) routine c
28010 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 an be called at
28020 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 any point during
28030 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 .** the life cyc
28040 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 le of [prepared
28050 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a statement] S:.**
28060 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e before statemen
28070 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c t S is ever eval
28080 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 uated, after.**
28090 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c one or more call
280a0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 s to [sqlite3_re
280b0 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 set()], or after
280c0 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 any call.** to
280d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
280e0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 regardless of w
280f0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 hether or not th
28100 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a e statement has.
28110 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 ** completed exe
28120 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 cution..**.** ^I
28130 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f nvoking sqlite3_
28140 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 finalize() on a
28150 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 NULL pointer is
28160 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 a harmless no-op
28170 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c ..**.** The appl
28180 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e ication must fin
28190 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 alize every [pre
281a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
281b0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f in order to avo
281c0 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c id.** resource l
281d0 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 eaks. It is a g
281e0 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f rievous error fo
281f0 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f r the applicatio
28200 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a n to try to use.
28210 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74 ** a prepared st
28220 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 atement after it
28230 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 has been finali
28240 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 zed. Any use of
28250 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 a prepared.** s
28260 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 tatement after i
28270 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c t has been final
28280 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 ized can result
28290 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 in undefined and
282a0 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 .** undesirable
282b0 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 behavior such as
282c0 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 segfaults and h
282d0 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a eap corruption..
282e0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
282f0 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 t sqlite3_finali
28300 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 ze(sqlite3_stmt
28310 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *pStmt);../*.**
28320 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 CAPI3REF: Reset
28330 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 A Prepared State
28340 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a ment Object.**.*
28350 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 * The sqlite3_re
28360 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 set() function i
28370 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 s called to rese
28380 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 t a [prepared st
28390 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 atement].** obje
283a0 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 ct back to its i
283b0 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 nitial state, re
283c0 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 ady to be re-exe
283d0 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 cuted..** ^Any S
283e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 QL statement var
283f0 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 iables that had
28400 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 values bound to
28410 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 them using.** th
28420 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f e [sqlite3_bind_
28430 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 blob | sqlite3_b
28440 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 ind_*() API] ret
28450 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 ain their values
28460 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 ..** Use [sqlite
28470 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 3_clear_bindings
28480 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 ()] to reset the
28490 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a bindings..**.**
284a0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 ^The [sqlite3_r
284b0 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 eset(S)] interfa
284c0 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 ce resets the [p
284d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
284e0 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 t] S.** back to
284f0 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 the beginning of
28500 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a its program..**
28510 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 .** ^If the most
28520 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 recent call to
28530 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 [sqlite3_step(S)
28540 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 ] for the.** [pr
28550 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
28560 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 ] S returned [SQ
28570 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 LITE_ROW] or [SQ
28580 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f LITE_DONE],.** o
28590 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 r if [sqlite3_st
285a0 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 ep(S)] has never
285b0 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c before been cal
285c0 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 led on S,.** the
285d0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 n [sqlite3_reset
285e0 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 (S)] returns [SQ
285f0 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 LITE_OK]..**.**
28600 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 ^If the most rec
28610 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ent call to [sql
28620 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f ite3_step(S)] fo
28630 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 r the.** [prepar
28640 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 ed statement] S
28650 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 indicated an err
28660 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c or, then.** [sql
28670 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 ite3_reset(S)] r
28680 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 eturns an approp
28690 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 riate [error cod
286a0 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b e]..**.** ^The [
286b0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 sqlite3_reset(S)
286c0 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 ] interface does
286d0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 not change the
286e0 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 values.** of any
286f0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
28700 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e lob|bindings] on
28710 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
28720 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a tatement] S..*/.
28730 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
28740 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c qlite3_reset(sql
28750 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
28760 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
28770 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 EF: Create Or Re
28780 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 define SQL Funct
28790 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ions.** KEYWORDS
287a0 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 : {function crea
287b0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a tion routines}.*
287c0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 * KEYWORDS: {app
287d0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
287e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a SQL function}.*
287f0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 * KEYWORDS: {app
28800 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
28810 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a SQL functions}.
28820 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e **.** ^These fun
28830 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 ctions (collecti
28840 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 vely known as "f
28850 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e unction creation
28860 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 routines").** a
28870 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 re used to add S
28880 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 QL functions or
28890 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f aggregates or to
288a0 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 redefine the be
288b0 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 havior.** of exi
288c0 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 sting SQL functi
288d0 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 ons or aggregate
288e0 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 s. The only dif
288f0 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e ferences between
28900 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e .** these routin
28910 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20 es are the text
28920 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 encoding expecte
28930 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 d for.** the sec
28940 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 ond parameter (t
28950 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 he name of the f
28960 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 unction being cr
28970 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 eated).** and th
28980 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 e presence or ab
28990 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 sence of a destr
289a0 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 uctor callback f
289b0 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 or.** the applic
289c0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 ation data point
289d0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 er..**.** ^The f
289e0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 irst parameter i
289f0 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 s the [database
28a00 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 connection] to w
28a10 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 hich the SQL.**
28a20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 function is to b
28a30 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e e added. ^If an
28a40 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 application use
28a50 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 s more than one
28a60 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
28a70 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c ection then appl
28a80 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
28a90 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 SQL functions mu
28aa0 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 st be added.** t
28ab0 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 o each database
28ac0 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 connection separ
28ad0 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ately..**.** ^Th
28ae0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
28af0 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f er is the name o
28b00 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 f the SQL functi
28b10 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 on to be created
28b20 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 or.** redefined
28b30 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f . ^The length o
28b40 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 f the name is li
28b50 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 mited to 255 byt
28b60 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a es in a UTF-8.**
28b70 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c representation,
28b80 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 exclusive of th
28b90 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f e zero-terminato
28ba0 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 r. ^Note that t
28bb0 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 he name.** lengt
28bc0 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 h limit is in UT
28bd0 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 F-8 bytes, not c
28be0 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 haracters nor UT
28bf0 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a F-16 bytes. .**
28c00 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f ^Any attempt to
28c10 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 create a functi
28c20 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 on with a longer
28c30 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 name.** will re
28c40 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f sult in [SQLITE_
28c50 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 MISUSE] being re
28c60 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 turned..**.** ^T
28c70 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
28c80 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 er (nArg).** is
28c90 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 the number of ar
28ca0 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 guments that the
28cb0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 SQL function or
28cc0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 .** aggregate ta
28cd0 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 kes. ^If this pa
28ce0 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 rameter is -1, t
28cf0 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 hen the SQL func
28d00 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 tion or.** aggre
28d10 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e gate may take an
28d20 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 y number of argu
28d30 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 ments between 0
28d40 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a and the limit.**
28d50 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 set by [sqlite3
28d60 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f _limit]([SQLITE_
28d70 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 LIMIT_FUNCTION_A
28d80 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 RG]). If the th
28d90 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ird.** parameter
28da0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 is less than -1
28db0 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e or greater than
28dc0 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 127 then the be
28dd0 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 havior is.** und
28de0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 efined..**.** ^T
28df0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
28e00 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 ter, eTextRep, s
28e10 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a pecifies what.**
28e20 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 [SQLITE_UTF8 |
28e30 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 text encoding] t
28e40 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e his SQL function
28e50 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 prefers for.**
28e60 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 its parameters.
28e70 20 45 76 65 72 79 20 53 51 4c 20 66 75 6e 63 74 Every SQL funct
28e80 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ion implementati
28e90 6f 6e 20 6d 75 73 74 20 62 65 20 61 62 6c 65 20 on must be able
28ea0 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20 to work.** with
28eb0 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c UTF-8, UTF-16le,
28ec0 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 or UTF-16be. B
28ed0 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e ut some implemen
28ee0 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a tations may be.*
28ef0 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 * more efficient
28f00 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 with one encodi
28f10 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e ng than another.
28f20 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f ^An applicatio
28f30 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 n may.** invoke
28f40 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
28f50 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c unction() or sql
28f60 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
28f70 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c tion16() multipl
28f80 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 e.** times with
28f90 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f the same functio
28fa0 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65 n but with diffe
28fb0 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65 rent values of e
28fc0 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 TextRep..** ^Whe
28fd0 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 n multiple imple
28fe0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 mentations of th
28ff0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 e same function
29000 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 are available, S
29010 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 QLite.** will pi
29020 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 ck the one that
29030 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 involves the lea
29040 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 st amount of dat
29050 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a a conversion..**
29060 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c If there is onl
29070 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 y a single imple
29080 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 mentation which
29090 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 does not care wh
290a0 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 at text.** encod
290b0 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 ing is used, the
290c0 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 n the fourth arg
290d0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 ument should be
290e0 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a [SQLITE_ANY]..**
290f0 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 .** ^(The fifth
29100 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 parameter is an
29110 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 arbitrary pointe
29120 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e r. The implemen
29130 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a tation of the.**
29140 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 function can ga
29150 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 in access to thi
29160 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 s pointer using
29170 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 [sqlite3_user_da
29180 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e ta()].)^.**.** ^
29190 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e The sixth, seven
291a0 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61 th and eighth pa
291b0 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c rameters, xFunc,
291c0 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 xStep and xFina
291d0 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 l, are.** pointe
291e0 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 rs to C-language
291f0 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 functions that
29200 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 implement the SQ
29210 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a L function or.**
29220 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 aggregate. ^A s
29230 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 calar SQL functi
29240 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 on requires an i
29250 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
29260 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 the xFunc.** ca
29270 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c llback only; NUL
29280 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 L pointers must
29290 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 be passed as the
292a0 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 xStep and xFina
292b0 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e l.** parameters.
292c0 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 ^An aggregate S
292d0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 QL function requ
292e0 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e ires an implemen
292f0 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a tation of xStep.
29300 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e ** and xFinal an
29310 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d d NULL pointer m
29320 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f ust be passed fo
29330 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c r xFunc. ^To del
29340 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a ete an existing.
29350 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 ** SQL function
29360 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 or aggregate, pa
29370 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 ss NULL pointers
29380 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 for all three f
29390 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 unction.** callb
293a0 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 acks..**.** ^(If
293b0 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d the ninth param
293c0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
293d0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f create_function_
293e0 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c v2() is not NULL
293f0 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 ,.** then it is
29400 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 destructor for t
29410 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 he application d
29420 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a ata pointer. .**
29430 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 The destructor
29440 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 is invoked when
29450 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 the function is
29460 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 deleted, either
29470 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 by being.** over
29480 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 loaded or when t
29490 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
294a0 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e ection closes.)^
294b0 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 .** ^The destruc
294c0 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f tor is also invo
294d0 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 ked if the call
294e0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 to.** sqlite3_cr
294f0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 eate_function_v2
29500 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 () fails..** ^Wh
29510 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f en the destructo
29520 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 r callback of th
29530 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 e tenth paramete
29540 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 r is invoked, it
29550 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 .** is passed a
29560 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
29570 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 which is a copy
29580 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 of the applicati
29590 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e on data .** poin
295a0 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68 ter which was th
295b0 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 e fifth paramete
295c0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 r to sqlite3_cre
295d0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 ate_function_v2(
295e0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 )..**.** ^It is
295f0 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 permitted to reg
29600 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 ister multiple i
29610 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f mplementations o
29620 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 f the same.** fu
29630 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 nctions with the
29640 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 same name but w
29650 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65 ith either diffe
29660 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a ring numbers of.
29670 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 ** arguments or
29680 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 differing prefer
29690 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e red text encodin
296a0 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c gs. ^SQLite wil
296b0 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 l use.** the imp
296c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 lementation that
296d0 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 most closely ma
296e0 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e tches the way in
296f0 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 which the.** SQ
29700 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 L function is us
29710 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e ed. ^A function
29720 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
29730 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 with a non-negat
29740 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 ive.** nArg para
29750 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65 meter is a bette
29760 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 r match than a f
29770 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e unction implemen
29780 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 tation with.** a
29790 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 negative nArg.
297a0 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 ^A function whe
297b0 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 re the preferred
297c0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a text encoding.*
297d0 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 * matches the da
297e0 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 tabase encoding
297f0 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d is a better.** m
29800 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 atch than a func
29810 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 tion where the e
29820 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 ncoding is diffe
29830 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 rent. .** ^A fu
29840 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 nction where the
29850 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 encoding differ
29860 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 ence is between
29870 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 UTF16le and UTF1
29880 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 6be.** is a clos
29890 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 er match than a
298a0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 function where t
298b0 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 he encoding diff
298c0 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 erence is.** bet
298d0 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 ween UTF8 and UT
298e0 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c F16..**.** ^Buil
298f0 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d t-in functions m
29900 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 ay be overloaded
29910 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 by new applicat
29920 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
29930 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e tions..**.** ^An
29940 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
29950 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 ined function is
29960 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 permitted to ca
29970 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 ll other.** SQLi
29980 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 te interfaces.
29990 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 However, such ca
299a0 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 lls must not.**
299b0 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 close the databa
299c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f se connection no
299d0 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 r finalize or re
299e0 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 set the prepared
299f0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e .** statement in
29a00 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 which the funct
29a10 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a ion is running..
29a20 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
29a30 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 t sqlite3_create
29a40 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c _function(. sql
29a50 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 ite3 *db,. cons
29a60 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f t char *zFunctio
29a70 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 nName,. int nAr
29a80 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 g,. int eTextRe
29a90 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c p,. void *pApp,
29aa0 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 . void (*xFunc)
29ab0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
29ac0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
29ad0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
29ae0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f *xStep)(sqlite3_
29af0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c context*,int,sql
29b00 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 ite3_value**),.
29b10 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 void (*xFinal)(
29b20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
29b30 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 ).);.SQLITE_API
29b40 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 int sqlite3_crea
29b50 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 te_function16(.
29b60 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 sqlite3 *db,.
29b70 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e const void *zFun
29b80 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 ctionName,. int
29b90 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 nArg,. int eTe
29ba0 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 xtRep,. void *p
29bb0 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 App,. void (*xF
29bc0 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e unc)(sqlite3_con
29bd0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 text*,int,sqlite
29be0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 3_value**),. vo
29bf0 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 id (*xStep)(sqli
29c00 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 te3_context*,int
29c10 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a ,sqlite3_value**
29c20 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e ),. void (*xFin
29c30 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 al)(sqlite3_cont
29c40 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f ext*).);.SQLITE_
29c50 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
29c60 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f create_function_
29c70 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 v2(. sqlite3 *d
29c80 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 b,. const char
29c90 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a *zFunctionName,.
29ca0 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e int nArg,. in
29cb0 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f t eTextRep,. vo
29cc0 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 id *pApp,. void
29cd0 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 (*xFunc)(sqlite
29ce0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 3_context*,int,s
29cf0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c qlite3_value**),
29d00 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 . void (*xStep)
29d10 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
29d20 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
29d30 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
29d40 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 *xFinal)(sqlite3
29d50 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f _context*),. vo
29d60 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f id(*xDestroy)(vo
29d70 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 id*).);../*.** C
29d80 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e API3REF: Text En
29d90 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 codings.**.** Th
29da0 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 ese constant def
29db0 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 ine integer code
29dc0 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 s that represent
29dd0 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 the various.**
29de0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 text encodings s
29df0 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 upported by SQLi
29e00 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 te..*/.#define S
29e10 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 QLITE_UTF8
29e20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 1.#define S
29e30 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 QLITE_UTF16LE
29e40 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 2.#define S
29e50 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 QLITE_UTF16BE
29e60 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 3.#define S
29e70 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 QLITE_UTF16
29e80 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 4 /* Use
29e90 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 native byte ord
29ea0 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 er */.#define SQ
29eb0 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 LITE_ANY
29ec0 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 5 /* sqli
29ed0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
29ee0 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 ion only */.#def
29ef0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 ine SQLITE_UTF16
29f00 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f _ALIGNED 8 /
29f10 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 * sqlite3_create
29f20 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 _collation only
29f30 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
29f40 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 EF: Deprecated F
29f50 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 unctions.** DEPR
29f60 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 ECATED.**.** The
29f70 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 se functions are
29f80 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 [deprecated].
29f90 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e In order to main
29fa0 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 tain.** backward
29fb0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 s compatibility
29fc0 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c with older code,
29fd0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 these functions
29fe0 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f continue .** to
29ff0 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 be supported.
2a000 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 However, new app
2a010 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 lications should
2a020 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 avoid.** the us
2a030 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 e of these funct
2a040 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 ions. To help e
2a050 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 ncourage people
2a060 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e to avoid.** usin
2a070 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e g these function
2a080 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f s, we are not go
2a090 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 ing to tell you
2a0a0 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f what they do..*/
2a0b0 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f .#ifndef SQLITE_
2a0c0 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a OMIT_DEPRECATED.
2a0d0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
2a0e0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 E_DEPRECATED int
2a0f0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 sqlite3_aggrega
2a100 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 te_count(sqlite3
2a110 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 _context*);.SQLI
2a120 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 TE_API SQLITE_DE
2a130 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c PRECATED int sql
2a140 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c ite3_expired(sql
2a150 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c ite3_stmt*);.SQL
2a160 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 ITE_API SQLITE_D
2a170 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 EPRECATED int sq
2a180 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 lite3_transfer_b
2a190 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f indings(sqlite3_
2a1a0 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 stmt*, sqlite3_s
2a1b0 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 tmt*);.SQLITE_AP
2a1c0 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 I SQLITE_DEPRECA
2a1d0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f TED int sqlite3_
2a1e0 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 global_recover(v
2a1f0 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 oid);.SQLITE_API
2a200 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 SQLITE_DEPRECAT
2a210 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f ED void sqlite3_
2a220 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 thread_cleanup(v
2a230 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 oid);.SQLITE_API
2a240 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 SQLITE_DEPRECAT
2a250 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d ED int sqlite3_m
2a260 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 emory_alarm(void
2a270 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 (*)(void*,sqlite
2a280 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 3_int64,int),voi
2a290 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 d*,sqlite3_int64
2a2a0 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a );.#endif../*.**
2a2b0 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 CAPI3REF: Obtai
2a2c0 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f ning SQL Functio
2a2d0 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 n Parameter Valu
2a2e0 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c es.**.** The C-l
2a2f0 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e anguage implemen
2a300 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 tation of SQL fu
2a310 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 nctions and aggr
2a320 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 egates uses.** t
2a330 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 his set of inter
2a340 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f face routines to
2a350 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61 access the para
2a360 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a meter values on.
2a370 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 ** the function
2a380 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a or aggregate..**
2a390 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 .** The xFunc (f
2a3a0 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 or scalar functi
2a3b0 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 ons) or xStep (f
2a3c0 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70 or aggregates) p
2a3d0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 arameters.** to
2a3e0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
2a3f0 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 function()] and
2a400 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
2a410 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a function16()].**
2a420 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b define callback
2a430 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 s that implement
2a440 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
2a450 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 ns and aggregate
2a460 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61 s..** The 3rd pa
2a470 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 rameter to these
2a480 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e callbacks is an
2a490 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 array of pointe
2a4a0 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 rs to.** [protec
2a4b0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
2a4c0 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 e] objects. The
2a4d0 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 re is one [sqlit
2a4e0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
2a4f0 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 for.** each par
2a500 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 ameter to the SQ
2a510 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 L function. The
2a520 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
2a530 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 used to.** extra
2a540 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 ct values from t
2a550 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 he [sqlite3_valu
2a560 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a e] objects..**.*
2a570 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
2a580 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 work only with
2a590 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 [protected sqlit
2a5a0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
2a5b0 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 s..** Any attemp
2a5c0 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 t to use these r
2a5d0 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 outines on an [u
2a5e0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
2a5f0 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a e3_value].** obj
2a600 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 ect results in u
2a610 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f ndefined behavio
2a620 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 r..**.** ^These
2a630 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 routines work ju
2a640 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 st like the corr
2a650 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d esponding [colum
2a660 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f n access functio
2a670 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 ns].** except th
2a680 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e at these routin
2a690 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 es take a single
2a6a0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 [protected sqli
2a6b0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
2a6c0 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 t.** pointer ins
2a6d0 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 tead of a [sqlit
2a6e0 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 e3_stmt*] pointe
2a6f0 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 r and an integer
2a700 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a column number..
2a710 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
2a720 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 e3_value_text16(
2a730 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 ) interface extr
2a740 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 acts a UTF-16 st
2a750 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e ring.** in the n
2a760 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 ative byte-order
2a770 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 of the host mac
2a780 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 hine. ^The.** s
2a790 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
2a7a0 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 t16be() and sqli
2a7b0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
2a7c0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a le() interfaces.
2a7d0 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 ** extract UTF-1
2a7e0 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 6 strings as big
2a7f0 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 -endian and litt
2a800 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 le-endian respec
2a810 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 tively..**.** ^(
2a820 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 The sqlite3_valu
2a830 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 e_numeric_type()
2a840 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d interface attem
2a850 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 pts to apply.**
2a860 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 numeric affinity
2a870 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 to the value.
2a880 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 This means that
2a890 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a an attempt is.**
2a8a0 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 made to convert
2a8b0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e the value to an
2a8c0 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 integer or floa
2a8d0 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a ting point. If.
2a8e0 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 ** such a conver
2a8f0 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 sion is possible
2a900 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 without loss of
2a910 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e information (in
2a920 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c other.** words,
2a930 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 if the value is
2a940 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c a string that l
2a950 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 ooks like a numb
2a960 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 er).** then the
2a970 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 conversion is pe
2a980 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 rformed. Otherw
2a990 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f ise no conversio
2a9a0 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 n occurs..** The
2a9b0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 [SQLITE_INTEGER
2a9c0 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 | datatype] aft
2a9d0 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 er conversion is
2a9e0 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a returned.)^.**.
2a9f0 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 ** Please pay pa
2aa00 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 rticular attenti
2aa10 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 on to the fact t
2aa20 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 hat the pointer
2aa30 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d returned.** from
2aa40 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
2aa50 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 blob()], [sqlite
2aa60 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 3_value_text()],
2aa70 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
2aa80 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 value_text16()]
2aa90 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 can be invalidat
2aaa0 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65 ed by a subseque
2aab0 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 nt call to.** [s
2aac0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 qlite3_value_byt
2aad0 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f es()], [sqlite3_
2aae0 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d value_bytes16()]
2aaf0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 , [sqlite3_value
2ab00 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 _text()],.** or
2ab10 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 [sqlite3_value_t
2ab20 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 ext16()]..**.**
2ab30 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d These routines m
2ab40 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 ust be called fr
2ab50 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 om the same thre
2ab60 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c ad as.** the SQL
2ab70 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 function that s
2ab80 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c upplied the [sql
2ab90 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 ite3_value*] par
2aba0 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 53 51 4c 49 ameters..*/.SQLI
2abb0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 TE_API const voi
2abc0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 d *sqlite3_value
2abd0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 _blob(sqlite3_va
2abe0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 lue*);.SQLITE_AP
2abf0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 I int sqlite3_va
2ac00 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 lue_bytes(sqlite
2ac10 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 3_value*);.SQLIT
2ac20 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
2ac30 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 3_value_bytes16(
2ac40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
2ac50 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 .SQLITE_API doub
2ac60 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 le sqlite3_value
2ac70 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f _double(sqlite3_
2ac80 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f value*);.SQLITE_
2ac90 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
2aca0 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 value_int(sqlite
2acb0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 3_value*);.SQLIT
2acc0 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e E_API sqlite3_in
2acd0 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 t64 sqlite3_valu
2ace0 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f e_int64(sqlite3_
2acf0 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f value*);.SQLITE_
2ad00 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e API const unsign
2ad10 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 ed char *sqlite3
2ad20 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 _value_text(sqli
2ad30 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c te3_value*);.SQL
2ad40 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f ITE_API const vo
2ad50 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 id *sqlite3_valu
2ad60 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 e_text16(sqlite3
2ad70 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 _value*);.SQLITE
2ad80 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 _API const void
2ad90 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 *sqlite3_value_t
2ada0 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f ext16le(sqlite3_
2adb0 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f value*);.SQLITE_
2adc0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a API const void *
2add0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
2ade0 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 xt16be(sqlite3_v
2adf0 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 alue*);.SQLITE_A
2ae00 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 PI int sqlite3_v
2ae10 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 alue_type(sqlite
2ae20 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 3_value*);.SQLIT
2ae30 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
2ae40 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 3_value_numeric_
2ae50 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c type(sqlite3_val
2ae60 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ue*);../*.** CAP
2ae70 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 I3REF: Obtain Ag
2ae80 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e gregate Function
2ae90 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 Context.**.** I
2aea0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f mplementations o
2aeb0 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 f aggregate SQL
2aec0 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 functions use th
2aed0 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f is.** routine to
2aee0 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 allocate memory
2aef0 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 for storing the
2af00 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 ir state..**.**
2af10 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 ^The first time
2af20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 the sqlite3_aggr
2af30 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c egate_context(C,
2af40 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 N) routine is ca
2af50 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 lled .** for a p
2af60 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 articular aggreg
2af70 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 ate function, SQ
2af80 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 Lite.** allocate
2af90 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a s N of memory, z
2afa0 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d eroes out that m
2afb0 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 emory, and retur
2afc0 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 ns a pointer.**
2afd0 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 to the new memor
2afe0 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e y. ^On second an
2aff0 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c d subsequent cal
2b000 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 ls to.** sqlite3
2b010 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
2b020 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d xt() for the sam
2b030 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 e aggregate func
2b040 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a tion instance,.*
2b050 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 * the same buffe
2b060 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 r is returned.
2b070 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 Sqlite3_aggregat
2b080 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e e_context() is n
2b090 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 ormally.** calle
2b0a0 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 d once for each
2b0b0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 invocation of th
2b0c0 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b e xStep callback
2b0d0 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a and then one.**
2b0e0 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 last time when
2b0f0 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 the xFinal callb
2b100 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 ack is invoked.
2b110 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 ^(When no rows
2b120 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 match.** an aggr
2b130 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 egate query, the
2b140 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 xStep() callbac
2b150 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 k of the aggrega
2b160 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 te function.** i
2b170 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 mplementation is
2b180 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e never called an
2b190 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 d xFinal() is ca
2b1a0 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 lled exactly onc
2b1b0 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 e..** In those c
2b1c0 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 ases, sqlite3_ag
2b1d0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 gregate_context(
2b1e0 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 ) might be calle
2b1f0 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 d for the.** fir
2b200 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 st time from wit
2b210 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a hin xFinal().)^.
2b220 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
2b230 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
2b240 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e text(C,N) routin
2b250 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c e returns a NULL
2b260 20 70 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73 pointer if N is
2b270 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 .** less than or
2b280 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f equal to zero o
2b290 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c r if a memory al
2b2a0 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 locate error occ
2b2b0 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 urs..**.** ^(The
2b2c0 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 amount of space
2b2d0 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 allocated by sq
2b2e0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
2b2f0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a context(C,N) is.
2b300 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 ** determined by
2b310 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 the N parameter
2b320 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 on first succes
2b330 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e sful call. Chan
2b340 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 ging the.** valu
2b350 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 e of N in subseq
2b360 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c uent call to sql
2b370 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
2b380 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a ontext() within.
2b390 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 ** the same aggr
2b3a0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 egate function i
2b3b0 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 nstance will not
2b3c0 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f resize the memo
2b3d0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e ry.** allocation
2b3e0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 .)^.**.** ^SQLit
2b3f0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 e automatically
2b400 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 frees the memory
2b410 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a allocated by .*
2b420 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 * sqlite3_aggreg
2b430 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 ate_context() wh
2b440 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 en the aggregate
2b450 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 query concludes
2b460 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 ..**.** The firs
2b470 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 t parameter must
2b480 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 be a copy of th
2b490 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f e.** [sqlite3_co
2b4a0 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 ntext | SQL func
2b4b0 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 tion context] th
2b4c0 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 at is the first
2b4d0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 parameter.** to
2b4e0 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 the xStep or xFi
2b4f0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 nal callback rou
2b500 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d tine that implem
2b510 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 ents the aggrega
2b520 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a te.** function..
2b530 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
2b540 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 ne must be calle
2b550 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 d from the same
2b560 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a thread in which.
2b570 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65 ** the aggregate
2b580 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 SQL function is
2b590 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c running..*/.SQL
2b5a0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 ITE_API void *sq
2b5b0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
2b5c0 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f context(sqlite3_
2b5d0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 context*, int nB
2b5e0 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ytes);../*.** CA
2b5f0 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 PI3REF: User Dat
2b600 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a a For Functions.
2b610 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
2b620 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 e3_user_data() i
2b630 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
2b640 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 a copy of.** th
2b650 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 e pointer that w
2b660 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61 as the pUserData
2b670 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 parameter (the
2b680 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 5th parameter).*
2b690 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 * of the [sqlite
2b6a0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
2b6b0 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c n()].** and [sql
2b6c0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
2b6d0 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e tion16()] routin
2b6e0 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c es that original
2b6f0 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 ly.** registered
2b700 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
2b710 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f defined functio
2b720 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f n..**.** This ro
2b730 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 utine must be ca
2b740 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 lled from the sa
2b750 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 me thread in whi
2b760 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 ch.** the applic
2b770 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
2b780 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e nction is runnin
2b790 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 g..*/.SQLITE_API
2b7a0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 void *sqlite3_u
2b7b0 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 ser_data(sqlite3
2b7c0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a _context*);../*.
2b7d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 ** CAPI3REF: Dat
2b7e0 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e abase Connection
2b7f0 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a For Functions.*
2b800 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
2b810 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 3_context_db_han
2b820 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 dle() interface
2b830 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f returns a copy o
2b840 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 f.** the pointer
2b850 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 to the [databas
2b860 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 e connection] (t
2b870 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 he 1st parameter
2b880 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c ).** of the [sql
2b890 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
2b8a0 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b tion()].** and [
2b8b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
2b8c0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 unction16()] rou
2b8d0 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 tines that origi
2b8e0 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 nally.** registe
2b8f0 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 red the applicat
2b900 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 ion defined func
2b910 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f tion..*/.SQLITE_
2b920 41 50 49 20 73 71 6c 69 74 65 33 20 2a 73 71 6c API sqlite3 *sql
2b930 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f ite3_context_db_
2b940 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 handle(sqlite3_c
2b950 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a ontext*);../*.**
2b960 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 CAPI3REF: Funct
2b970 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 ion Auxiliary Da
2b980 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c ta.**.** The fol
2b990 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 lowing two funct
2b9a0 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 ions may be used
2b9b0 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66 by scalar SQL f
2b9c0 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 unctions to.** a
2b9d0 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 ssociate metadat
2b9e0 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 a with argument
2b9f0 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 values. If the s
2ba00 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 ame value is pas
2ba10 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 sed to.** multip
2ba20 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f le invocations o
2ba30 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 f the same SQL f
2ba40 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 unction during q
2ba50 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 uery execution,
2ba60 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 under.** some ci
2ba70 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 rcumstances the
2ba80 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 associated metad
2ba90 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 ata may be prese
2baa0 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a rved. This may.*
2bab0 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 * be used, for e
2bac0 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 xample, to add a
2bad0 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 regular-express
2bae0 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 ion matching sca
2baf0 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e lar.** function.
2bb00 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 The compiled ve
2bb10 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 rsion of the reg
2bb20 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 ular expression
2bb30 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 is stored as.**
2bb40 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 metadata associa
2bb50 74 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c ted with the SQL
2bb60 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 value passed as
2bb70 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 the regular exp
2bb80 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 ression.** patte
2bb90 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 rn. The compile
2bba0 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 d regular expres
2bbb0 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 sion can be reus
2bbc0 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a ed on multiple.*
2bbd0 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 * invocations of
2bbe0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 the same functi
2bbf0 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f on so that the o
2bc00 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 riginal pattern
2bc10 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e string.** does n
2bc20 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 ot need to be re
2bc30 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 compiled on each
2bc40 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a invocation..**.
2bc50 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2bc60 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e get_auxdata() in
2bc70 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
2bc80 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
2bc90 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 metadata.** ass
2bca0 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73 ociated by the s
2bcb0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 qlite3_set_auxda
2bcc0 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 ta() function wi
2bcd0 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d th the Nth argum
2bce0 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 ent.** value to
2bcf0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
2bd00 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
2bd10 2e 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 . ^If no metadat
2bd20 61 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a a has been ever.
2bd30 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 ** been set for
2bd40 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 the Nth argument
2bd50 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e of the function
2bd60 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 , or if the corr
2bd70 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e esponding.** fun
2bd80 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 ction parameter
2bd90 68 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 has changed sinc
2bda0 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 e the meta-data
2bdb0 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e was set,.** then
2bdc0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 sqlite3_get_aux
2bdd0 64 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 data() returns a
2bde0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a NULL pointer..*
2bdf0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
2be00 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 3_set_auxdata()
2be10 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20 interface saves
2be20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 the metadata.**
2be30 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 pointed to by it
2be40 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 s 3rd parameter
2be50 61 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 as the metadata
2be60 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 for the N-th.**
2be70 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 argument of the
2be80 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
2be90 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 ned function. S
2bea0 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c ubsequent.** cal
2beb0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 ls to sqlite3_ge
2bec0 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 t_auxdata() migh
2bed0 74 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 t return this da
2bee0 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a ta, if it has.**
2bef0 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f not been destro
2bf00 79 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 yed..** ^If it i
2bf10 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 s not NULL, SQLi
2bf20 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 te will invoke t
2bf30 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a he destructor.**
2bf40 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 function given
2bf50 62 79 20 74 68 65 20 34 74 68 20 70 61 72 61 6d by the 4th param
2bf60 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
2bf70 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e set_auxdata() on
2bf80 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61 .** the metadata
2bf90 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 when the corres
2bfa0 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e ponding function
2bfb0 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 parameter chang
2bfc0 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 es.** or when th
2bfd0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
2bfe0 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68 completes, which
2bff0 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 ever comes first
2c000 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 ..**.** SQLite i
2c010 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 s free to call t
2c020 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e he destructor an
2c030 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20 d drop metadata
2c040 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 on any.** parame
2c050 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 ter of any funct
2c060 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e ion at any time.
2c070 20 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 ^The only guar
2c080 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a antee is that.**
2c090 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 the destructor
2c0a0 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 will be called b
2c0b0 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61 efore the metada
2c0c0 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a ta is dropped..*
2c0d0 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 *.** ^(In practi
2c0e0 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 ce, metadata is
2c0f0 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65 preserved betwee
2c100 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 n function calls
2c110 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 for.** expressi
2c120 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e ons that are con
2c130 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 stant at compile
2c140 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c time. This incl
2c150 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 udes literal.**
2c160 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 values and [para
2c170 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a meters].)^.**.**
2c180 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
2c190 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 must be called f
2c1a0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 rom the same thr
2c1b0 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 ead in which.**
2c1c0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
2c1d0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a is running..*/.
2c1e0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
2c1f0 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 *sqlite3_get_aux
2c200 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e data(sqlite3_con
2c210 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 text*, int N);.S
2c220 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
2c230 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 qlite3_set_auxda
2c240 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ta(sqlite3_conte
2c250 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 xt*, int N, void
2c260 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 *, void (*)(void
2c270 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 *));.../*.** CAP
2c280 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 I3REF: Constants
2c290 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 Defining Specia
2c2a0 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 l Destructor Beh
2c2b0 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 avior.**.** Thes
2c2c0 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 e are special va
2c2d0 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 lues for the des
2c2e0 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 tructor that is
2c2f0 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 passed in as the
2c300 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 .** final argume
2c310 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c nt to routines l
2c320 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 ike [sqlite3_res
2c330 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 ult_blob()]. ^I
2c340 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 f the destructor
2c350 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 .** argument is
2c360 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 SQLITE_STATIC, i
2c370 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 t means that the
2c380 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 content pointer
2c390 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 is constant.**
2c3a0 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 and will never c
2c3b0 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 hange. It does
2c3c0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 not need to be d
2c3d0 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a estroyed. ^The.
2c3e0 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 ** SQLITE_TRANSI
2c3f0 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 ENT value means
2c400 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 that the content
2c410 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 will likely cha
2c420 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 nge in.** the ne
2c430 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 ar future and th
2c440 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 at SQLite should
2c450 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 make its own pr
2c460 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a ivate copy of.**
2c470 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 the content bef
2c480 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a ore returning..*
2c490 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 *.** The typedef
2c4a0 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f is necessary to
2c4b0 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f work around pro
2c4c0 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e blems in certain
2c4d0 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 .** C++ compiler
2c4e0 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 s. See ticket #
2c4f0 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 2191..*/.typedef
2c500 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f void (*sqlite3_
2c510 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 destructor_type)
2c520 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 (void*);.#define
2c530 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 SQLITE_STATIC
2c540 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 ((sqlite3_de
2c550 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 structor_type)0)
2c560 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2c570 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 TRANSIENT ((sq
2c580 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 lite3_destructor
2c590 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a _type)-1)../*.**
2c5a0 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 CAPI3REF: Setti
2c5b0 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 ng The Result Of
2c5c0 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e An SQL Function
2c5d0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
2c5e0 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 tines are used b
2c5f0 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 y the xFunc or x
2c600 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 Final callbacks
2c610 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e that.** implemen
2c620 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 t SQL functions
2c630 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 and aggregates.
2c640 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 See.** [sqlite3
2c650 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
2c660 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
2c670 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
2c680 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 16()].** for add
2c690 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 itional informat
2c6a0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ion..**.** These
2c6b0 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 functions work
2c6c0 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 very much like t
2c6d0 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 he [parameter bi
2c6e0 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 nding] family of
2c6f0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 .** functions us
2c700 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 ed to bind value
2c710 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 s to host parame
2c720 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 ters in prepared
2c730 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 statements..**
2c740 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 Refer to the [SQ
2c750 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 L parameter] doc
2c760 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 umentation for a
2c770 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d dditional inform
2c780 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ation..**.** ^Th
2c790 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
2c7a0 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 _blob() interfac
2c7b0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c e sets the resul
2c7c0 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 t from.** an app
2c7d0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
2c7e0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
2c7f0 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 the BLOB whose c
2c800 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 ontent is pointe
2c810 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 d.** to by the s
2c820 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
2c830 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 and which is N b
2c840 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 ytes long where
2c850 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 N is the.** thir
2c860 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a d parameter..**.
2c870 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2c880 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 result_zeroblob(
2c890 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 ) interfaces set
2c8a0 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a the result of.*
2c8b0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f * the applicatio
2c8c0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
2c8d0 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 on to be a BLOB
2c8e0 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a containing all z
2c8f0 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 ero.** bytes and
2c900 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 N bytes in size
2c910 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 , where N is the
2c920 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e value of the 2n
2c930 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a d parameter..**.
2c940 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2c950 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 result_double()
2c960 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 interface sets t
2c970 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a he result from.*
2c980 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e * an application
2c990 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
2c9a0 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 n to be a floati
2c9b0 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 ng point value s
2c9c0 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 pecified.** by i
2c9d0 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e ts 2nd argument.
2c9e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2c9f0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
2ca00 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 () and sqlite3_r
2ca10 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 esult_error16()
2ca20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 functions.** cau
2ca30 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 se the implement
2ca40 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 ed SQL function
2ca50 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 to throw an exce
2ca60 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 ption..** ^SQLit
2ca70 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e e uses the strin
2ca80 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 g pointed to by
2ca90 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d the.** 2nd param
2caa0 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f eter of sqlite3_
2cab0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f result_error() o
2cac0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 r sqlite3_result
2cad0 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 _error16().** as
2cae0 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 the text of an
2caf0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 error message.
2cb00 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 ^SQLite interpre
2cb10 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 ts the error.**
2cb20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 message string f
2cb30 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 rom sqlite3_resu
2cb40 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 lt_error() as UT
2cb50 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 F-8. ^SQLite.**
2cb60 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73 interprets the s
2cb70 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 tring from sqlit
2cb80 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 e3_result_error1
2cb90 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 6() as UTF-16 in
2cba0 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 native.** byte
2cbb0 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20 order. ^If the
2cbc0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
2cbd0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c to sqlite3_resul
2cbe0 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 t_error().** or
2cbf0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
2cc00 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 rror16() is nega
2cc10 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 tive then SQLite
2cc20 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 takes as the er
2cc30 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 ror.** message a
2cc40 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 ll text up throu
2cc50 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 gh the first zer
2cc60 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 o character..**
2cc70 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 ^If the third pa
2cc80 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
2cc90 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 e3_result_error(
2cca0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ) or.** sqlite3_
2ccb0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 result_error16()
2ccc0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 is non-negative
2ccd0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b then SQLite tak
2cce0 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 es that many.**
2ccf0 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 bytes (not chara
2cd00 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 cters) from the
2cd10 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 2nd parameter as
2cd20 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 the error messa
2cd30 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 ge..** ^The sqli
2cd40 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
2cd50 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 () and sqlite3_r
2cd60 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a esult_error16().
2cd70 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 ** routines make
2cd80 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 a private copy
2cd90 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 of the error mes
2cda0 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 sage text before
2cdb0 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e .** they return.
2cdc0 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c Hence, the cal
2cdd0 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 ling function ca
2cde0 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a n deallocate or.
2cdf0 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 ** modify the te
2ce00 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65 xt after they re
2ce10 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 turn without har
2ce20 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 m..** ^The sqlit
2ce30 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f e3_result_error_
2ce40 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 code() function
2ce50 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f changes the erro
2ce60 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e r code.** return
2ce70 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 ed by SQLite as
2ce80 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 a result of an e
2ce90 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 rror in a functi
2cea0 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74 on. ^By default
2ceb0 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 ,.** the error c
2cec0 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 ode is SQLITE_ER
2ced0 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75 ROR. ^A subsequ
2cee0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 ent call to sqli
2cef0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
2cf00 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 ().** or sqlite3
2cf10 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
2cf20 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72 ) resets the err
2cf30 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 or code to SQLIT
2cf40 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e E_ERROR..**.** ^
2cf50 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
2cf60 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 lt_toobig() inte
2cf70 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c rface causes SQL
2cf80 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 ite to throw an
2cf90 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 error.** indicat
2cfa0 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e ing that a strin
2cfb0 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f g or BLOB is too
2cfc0 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 long to represe
2cfd0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 nt..**.** ^The s
2cfe0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f qlite3_result_no
2cff0 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 mem() interface
2d000 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f causes SQLite to
2d010 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a throw an error.
2d020 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 ** indicating th
2d030 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f at a memory allo
2d040 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a cation failed..*
2d050 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
2d060 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 3_result_int() i
2d070 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 nterface sets th
2d080 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a e return value.*
2d090 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 * of the applica
2d0a0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
2d0b0 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 ction to be the
2d0c0 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 32-bit signed in
2d0d0 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 teger.** value g
2d0e0 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 iven in the 2nd
2d0f0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 argument..** ^Th
2d100 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
2d110 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 _int64() interfa
2d120 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 ce sets the retu
2d130 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 rn value.** of t
2d140 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
2d150 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
2d160 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 to be the 64-bit
2d170 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a signed integer.
2d180 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 ** value given i
2d190 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 n the 2nd argume
2d1a0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 nt..**.** ^The s
2d1b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 qlite3_result_nu
2d1c0 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 ll() interface s
2d1d0 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 ets the return v
2d1e0 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 alue.** of the a
2d1f0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
2d200 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ed function to b
2d210 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 e NULL..**.** ^T
2d220 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
2d230 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 t_text(), sqlite
2d240 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 3_result_text16(
2d250 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 ),.** sqlite3_re
2d260 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c sult_text16le(),
2d270 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 and sqlite3_res
2d280 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 ult_text16be() i
2d290 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 nterfaces.** set
2d2a0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
2d2b0 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 e of the applica
2d2c0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
2d2d0 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 ction to be.** a
2d2e0 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 text string whi
2d2f0 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 ch is represente
2d300 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d d as UTF-8, UTF-
2d310 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 16 native byte o
2d320 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 rder,.** UTF-16
2d330 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f little endian, o
2d340 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 r UTF-16 big end
2d350 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c ian, respectivel
2d360 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 y..** ^SQLite ta
2d370 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73 kes the text res
2d380 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 ult from the app
2d390 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a lication from.**
2d3a0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
2d3b0 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 er of the sqlite
2d3c0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 3_result_text* i
2d3d0 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 nterfaces..** ^I
2d3e0 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 f the 3rd parame
2d3f0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ter to the sqlit
2d400 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 e3_result_text*
2d410 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 interfaces.** is
2d420 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 negative, then
2d430 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 SQLite takes res
2d440 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 ult text from th
2d450 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a e 2nd parameter.
2d460 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 ** through the f
2d470 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 irst zero charac
2d480 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ter..** ^If the
2d490 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 3rd parameter to
2d4a0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 the sqlite3_res
2d4b0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 ult_text* interf
2d4c0 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e aces.** is non-n
2d4d0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 egative, then as
2d4e0 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 many bytes (not
2d4f0 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 characters) of
2d500 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e the text.** poin
2d510 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e ted to by the 2n
2d520 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 d parameter are
2d530 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 taken as the app
2d540 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
2d550 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 .** function res
2d560 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ult..** ^If the
2d570 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 4th parameter to
2d580 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 the sqlite3_res
2d590 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 ult_text* interf
2d5a0 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 aces.** or sqlit
2d5b0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 e3_result_blob i
2d5c0 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 s a non-NULL poi
2d5d0 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 nter, then SQLit
2d5e0 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 e calls that.**
2d5f0 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 function as the
2d600 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 destructor on th
2d610 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 e text or BLOB r
2d620 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 esult when it ha
2d630 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 s.** finished us
2d640 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e ing that result.
2d650 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 .** ^If the 4th
2d660 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
2d670 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
2d680 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 text* interfaces
2d690 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 or to.** sqlite
2d6a0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 3_result_blob is
2d6b0 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e the special con
2d6c0 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 stant SQLITE_STA
2d6d0 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 TIC, then SQLite
2d6e0 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 .** assumes that
2d6f0 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f the text or BLO
2d700 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 B result is in c
2d710 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e onstant space an
2d720 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f d does not.** co
2d730 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f py the content o
2d740 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 f the parameter
2d750 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 nor call a destr
2d760 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e uctor on the con
2d770 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 tent.** when it
2d780 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 has finished usi
2d790 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a ng that result..
2d7a0 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 ** ^If the 4th p
2d7b0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
2d7c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
2d7d0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a ext* interfaces.
2d7e0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 ** or sqlite3_re
2d7f0 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 sult_blob is the
2d800 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e special constan
2d810 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 t SQLITE_TRANSIE
2d820 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 NT.** then SQLit
2d830 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f e makes a copy o
2d840 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 f the result int
2d850 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 o space obtained
2d860 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 from.** from [s
2d870 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
2d880 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 before it retur
2d890 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ns..**.** ^The s
2d8a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 qlite3_result_va
2d8b0 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 lue() interface
2d8c0 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 sets the result
2d8d0 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 of.** the applic
2d8e0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
2d8f0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 nction to be a c
2d900 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 opy the.** [unpr
2d910 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
2d920 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 value] object sp
2d930 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32 ecified by the 2
2d940 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e nd parameter. ^
2d950 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 The.** sqlite3_r
2d960 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e esult_value() in
2d970 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 terface makes a
2d980 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c copy of the [sql
2d990 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 ite3_value].** s
2d9a0 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 o that the [sqli
2d9b0 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 te3_value] speci
2d9c0 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 fied in the para
2d9d0 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 meter may change
2d9e0 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f or.** be deallo
2d9f0 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 cated after sqli
2da00 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 te3_result_value
2da10 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f () returns witho
2da20 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b ut harm..** ^A [
2da30 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
2da40 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
2da50 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 may always be us
2da60 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b ed where an.** [
2da70 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 unprotected sqli
2da80 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
2da90 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 t is required, s
2daa0 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 o either.** kind
2dab0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c of [sqlite3_val
2dac0 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 ue] object can b
2dad0 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73 e used with this
2dae0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a interface..**.*
2daf0 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 * If these routi
2db00 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 nes are called f
2db10 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 rom within the d
2db20 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a ifferent thread.
2db30 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 ** than the one
2db40 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 containing the a
2db50 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
2db60 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 ed function that
2db70 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 received.** the
2db80 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 [sqlite3_contex
2db90 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 t] pointer, the
2dba0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 results are unde
2dbb0 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 fined..*/.SQLITE
2dbc0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 _API void sqlite
2dbd0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 3_result_blob(sq
2dbe0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
2dbf0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
2dc00 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 , void(*)(void*)
2dc10 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f );.SQLITE_API vo
2dc20 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
2dc30 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 t_double(sqlite3
2dc40 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c _context*, doubl
2dc50 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 e);.SQLITE_API v
2dc60 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
2dc70 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 lt_error(sqlite3
2dc80 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 _context*, const
2dc90 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 53 51 char*, int);.SQ
2dca0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 LITE_API void sq
2dcb0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
2dcc0 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e or16(sqlite3_con
2dcd0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 text*, const voi
2dce0 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 d*, int);.SQLITE
2dcf0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 _API void sqlite
2dd00 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 3_result_error_t
2dd10 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f oobig(sqlite3_co
2dd20 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f ntext*);.SQLITE_
2dd30 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 API void sqlite3
2dd40 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f _result_error_no
2dd50 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 mem(sqlite3_cont
2dd60 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 ext*);.SQLITE_AP
2dd70 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 I void sqlite3_r
2dd80 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 esult_error_code
2dd90 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
2dda0 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f *, int);.SQLITE_
2ddb0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 API void sqlite3
2ddc0 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 _result_int(sqli
2ddd0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e te3_context*, in
2dde0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 t);.SQLITE_API v
2ddf0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
2de00 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 lt_int64(sqlite3
2de10 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 _context*, sqlit
2de20 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 e3_int64);.SQLIT
2de30 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 E_API void sqlit
2de40 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 e3_result_null(s
2de50 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 qlite3_context*)
2de60 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 ;.SQLITE_API voi
2de70 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
2de80 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f _text(sqlite3_co
2de90 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 ntext*, const ch
2dea0 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a ar*, int, void(*
2deb0 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 )(void*));.SQLIT
2dec0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 E_API void sqlit
2ded0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 e3_result_text16
2dee0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
2def0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 *, const void*,
2df00 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 int, void(*)(voi
2df10 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 d*));.SQLITE_API
2df20 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 void sqlite3_re
2df30 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 sult_text16le(sq
2df40 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
2df50 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
2df60 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 ,void(*)(void*))
2df70 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 ;.SQLITE_API voi
2df80 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
2df90 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 _text16be(sqlite
2dfa0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 3_context*, cons
2dfb0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 t void*, int,voi
2dfc0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 d(*)(void*));.SQ
2dfd0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 LITE_API void sq
2dfe0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c lite3_result_val
2dff0 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ue(sqlite3_conte
2e000 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c xt*, sqlite3_val
2e010 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ue*);.SQLITE_API
2e020 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 void sqlite3_re
2e030 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 sult_zeroblob(sq
2e040 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
2e050 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 int n);../*.** C
2e060 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 API3REF: Define
2e070 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 New Collating Se
2e080 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 quences.**.** ^T
2e090 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 hese functions a
2e0a0 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d dd, remove, or m
2e0b0 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 odify a [collati
2e0c0 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a on] associated.*
2e0d0 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 * with the [data
2e0e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
2e0f0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68 specified as th
2e100 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
2e110 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d ..**.** ^The nam
2e120 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 e of the collati
2e130 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 on is a UTF-8 st
2e140 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 ring.** for sqli
2e150 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
2e160 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 tion() and sqlit
2e170 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
2e180 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 ion_v2().** and
2e190 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 a UTF-16 string
2e1a0 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f in native byte o
2e1b0 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 rder for sqlite3
2e1c0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
2e1d0 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 n16()..** ^Colla
2e1e0 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 tion names that
2e1f0 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63 compare equal ac
2e200 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 cording to [sqli
2e210 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 te3_strnicmp()]
2e220 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 are.** considere
2e230 64 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65 d to be the same
2e240 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 name..**.** ^(T
2e250 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e he third argumen
2e260 74 20 28 65 54 65 78 74 52 65 70 29 20 6d 75 73 t (eTextRep) mus
2e270 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 t be one of the
2e280 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 constants:.** <u
2e290 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 l>.** <li> [SQLI
2e2a0 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 TE_UTF8],.** <li
2e2b0 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c > [SQLITE_UTF16L
2e2c0 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c E],.** <li> [SQL
2e2d0 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a ITE_UTF16BE],.**
2e2e0 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 <li> [SQLITE_UT
2e2f0 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e F16], or.** <li>
2e300 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 [SQLITE_UTF16_A
2e310 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c LIGNED]..** </ul
2e320 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 >)^.** ^The eTex
2e330 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65 tRep argument de
2e340 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 termines the enc
2e350 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 oding of strings
2e360 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 passed.** to th
2e370 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 e collating func
2e380 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 tion callback, x
2e390 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 Callback..** ^Th
2e3a0 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d e [SQLITE_UTF16]
2e3b0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 and [SQLITE_UTF
2e3c0 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 16_ALIGNED] valu
2e3d0 65 73 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a es for eTextRep.
2e3e0 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73 ** force strings
2e3f0 20 74 6f 20 62 65 20 55 54 46 31 36 20 77 69 74 to be UTF16 wit
2e400 68 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 h native byte or
2e410 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 der..** ^The [SQ
2e420 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e LITE_UTF16_ALIGN
2e430 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54 ED] value for eT
2e440 65 78 74 52 65 70 20 66 6f 72 63 65 73 20 73 74 extRep forces st
2e450 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a rings to begin.*
2e460 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 * on an even byt
2e470 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a e address..**.**
2e480 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 ^The fourth arg
2e490 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 ument, pArg, is
2e4a0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 an application d
2e4b0 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 ata pointer that
2e4c0 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 is passed.** th
2e4d0 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 rough as the fir
2e4e0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 st argument to t
2e4f0 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e he collating fun
2e500 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a ction callback..
2e510 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 **.** ^The fifth
2e520 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c argument, xCall
2e530 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 back, is a point
2e540 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 er to the collat
2e550 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a ing function..**
2e560 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 ^Multiple colla
2e570 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 ting functions c
2e580 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64 an be registered
2e590 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 using the same
2e5a0 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 name but.** with
2e5b0 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 different eText
2e5c0 52 65 70 20 70 61 72 61 6d 65 74 65 72 73 20 61 Rep parameters a
2e5d0 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 nd SQLite will u
2e5e0 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 se whichever.**
2e5f0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 function require
2e600 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 s the least amou
2e610 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73 nt of data trans
2e620 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 formation..** ^I
2e630 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 f the xCallback
2e640 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c argument is NULL
2e650 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 then the collat
2e660 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a ing function is.
2e670 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 ** deleted. ^Wh
2e680 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 en all collating
2e690 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e functions havin
2e6a0 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 g the same name
2e6b0 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 are deleted,.**
2e6c0 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 that collation i
2e6d0 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 s no longer usab
2e6e0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 le..**.** ^The c
2e6f0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f ollating functio
2e700 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e n callback is in
2e710 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70 voked with a cop
2e720 79 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a y of the pArg .*
2e730 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 * application da
2e740 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 ta pointer and w
2e750 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20 ith two strings
2e760 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 in the encoding
2e770 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 specified.** by
2e780 74 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67 the eTextRep arg
2e790 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c ument. The coll
2e7a0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d ating function m
2e7b0 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a ust return an.**
2e7c0 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 69 73 integer that is
2e7d0 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c negative, zero,
2e7e0 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 or positive.**
2e7f0 69 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72 if the first str
2e800 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e ing is less than
2e810 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 , equal to, or g
2e820 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 reater than the
2e830 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 second,.** respe
2e840 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c ctively. A coll
2e850 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d ating function m
2e860 75 73 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 ust always retur
2e870 6e 20 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65 n the same answe
2e880 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73 r.** given the s
2e890 61 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20 ame inputs. If
2e8a0 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c two or more coll
2e8b0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 ating functions
2e8c0 61 72 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a are registered.*
2e8d0 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f * to the same co
2e8e0 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 llation name (us
2e8f0 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20 65 54 ing different eT
2e900 65 78 74 52 65 70 20 76 61 6c 75 65 73 29 20 74 extRep values) t
2e910 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 hen all.** must
2e920 67 69 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65 give an equivale
2e930 6e 74 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69 nt answer when i
2e940 6e 76 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69 nvoked with equi
2e950 76 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a valent strings..
2e960 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 ** The collating
2e970 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f function must o
2e980 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e bey the followin
2e990 67 20 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72 g properties for
2e9a0 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 all.** strings
2e9b0 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a A, B, and C:.**.
2e9c0 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ol>.** <li>
2e9d0 49 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d If A==B then B==
2e9e0 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d A..** <li> If A=
2e9f0 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e =B and B==C then
2ea00 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 A==C..** <li> I
2ea10 66 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 f A<B THEN B&
2ea20 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 gt;A..** <li> If
2ea30 20 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 A<B and B<
2ea40 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a ;C then A<C..
2ea50 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 ** </ol>.**.** I
2ea60 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 f a collating fu
2ea70 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 nction fails any
2ea80 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f of the above co
2ea90 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68 nstraints and th
2eaa0 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 at.** collating
2eab0 66 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67 function is reg
2eac0 69 73 74 65 72 65 64 20 61 6e 64 20 75 73 65 64 istered and used
2ead0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 , then the behav
2eae0 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a ior of SQLite.**
2eaf0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a is undefined..*
2eb00 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
2eb10 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
2eb20 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 on_v2() works li
2eb30 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 ke sqlite3_creat
2eb40 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a e_collation().**
2eb50 20 77 69 74 68 20 74 68 65 20 61 64 64 69 74 69 with the additi
2eb60 6f 6e 20 74 68 61 74 20 74 68 65 20 78 44 65 73 on that the xDes
2eb70 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 troy callback is
2eb80 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 invoked on pArg
2eb90 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c when.** the col
2eba0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 lating function
2ebb0 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e is deleted..** ^
2ebc0 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 Collating functi
2ebd0 6f 6e 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 ons are deleted
2ebe0 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 when they are ov
2ebf0 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 erridden by late
2ec00 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 r.** calls to th
2ec10 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 e collation crea
2ec20 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f tion functions o
2ec30 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 r when the.** [d
2ec40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2ec50 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73 on] is closed us
2ec60 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f ing [sqlite3_clo
2ec70 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 se()]..**.** ^Th
2ec80 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 e xDestroy callb
2ec90 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 ack is <u>not</u
2eca0 3e 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20 > called if the
2ecb0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 .** sqlite3_crea
2ecc0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 te_collation_v2(
2ecd0 29 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 ) function fails
2ece0 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 . Applications
2ecf0 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 that invoke.** s
2ed00 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
2ed10 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 llation_v2() wit
2ed20 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 h a non-NULL xDe
2ed30 73 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 stroy argument s
2ed40 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 hould .** check
2ed50 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 the return code
2ed60 61 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74 and dispose of t
2ed70 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 he application d
2ed80 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 ata pointer.** t
2ed90 68 65 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72 hemselves rather
2eda0 20 74 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20 than expecting
2edb0 53 51 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77 SQLite to deal w
2edc0 69 74 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e ith it for them.
2edd0 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 69 66 66 .** This is diff
2ede0 65 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 erent from every
2edf0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e other SQLite in
2ee00 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e terface. The in
2ee10 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 consistency .**
2ee20 69 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 is unfortunate b
2ee30 75 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 ut cannot be cha
2ee40 6e 67 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 nged without bre
2ee50 61 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20 aking backwards
2ee60 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 .** compatibilit
2ee70 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 y..**.** See als
2ee80 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c o: [sqlite3_col
2ee90 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d lation_needed()]
2eea0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f and [sqlite3_co
2eeb0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 llation_needed16
2eec0 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ()]..*/.SQLITE_A
2eed0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 PI int sqlite3_c
2eee0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 reate_collation(
2eef0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 . sqlite3*, .
2ef00 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
2ef10 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 e, . int eTextR
2ef20 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 ep, . void *pAr
2ef30 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 g,. int(*xCompa
2ef40 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f re)(void*,int,co
2ef50 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f nst void*,int,co
2ef60 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 nst void*).);.SQ
2ef70 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
2ef80 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
2ef90 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 ation_v2(. sqli
2efa0 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 te3*, . const c
2efb0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 har *zName, . i
2efc0 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 nt eTextRep, .
2efd0 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e void *pArg,. in
2efe0 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 t(*xCompare)(voi
2eff0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 d*,int,const voi
2f000 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 d*,int,const voi
2f010 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 d*),. void(*xDe
2f020 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b stroy)(void*).);
2f030 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
2f040 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
2f050 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 ollation16(. sq
2f060 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 lite3*, . const
2f070 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 void *zName,.
2f080 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 int eTextRep, .
2f090 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 void *pArg,. i
2f0a0 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f nt(*xCompare)(vo
2f0b0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f id*,int,const vo
2f0c0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f id*,int,const vo
2f0d0 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 id*).);../*.** C
2f0e0 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 API3REF: Collati
2f0f0 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 on Needed Callba
2f100 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 cks.**.** ^To av
2f110 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 oid having to re
2f120 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 gister all colla
2f130 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 tion sequences b
2f140 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 efore a database
2f150 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c .** can be used,
2f160 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 a single callba
2f170 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 ck function may
2f180 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69 be registered wi
2f190 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 th the.** [datab
2f1a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
2f1b0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 to be invoked wh
2f1c0 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 enever an undefi
2f1d0 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a ned collation.**
2f1e0 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 sequence is req
2f1f0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 uired..**.** ^If
2f200 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 the function is
2f210 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e registered usin
2f220 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f g the sqlite3_co
2f230 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 llation_needed()
2f240 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 API,.** then it
2f250 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e is passed the n
2f260 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 ames of undefine
2f270 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 d collation sequ
2f280 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 ences as strings
2f290 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 .** encoded in U
2f2a0 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 TF-8. ^If sqlite
2f2b0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 3_collation_need
2f2c0 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a ed16() is used,.
2f2d0 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 ** the names are
2f2e0 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 passed as UTF-1
2f2f0 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 6 in machine nat
2f300 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a ive byte order..
2f310 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 ** ^A call to ei
2f320 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 ther function re
2f330 70 6c 61 63 65 73 20 74 68 65 20 65 78 69 73 74 places the exist
2f340 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 ing collation-ne
2f350 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a eded callback..*
2f360 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 *.** ^(When the
2f370 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
2f380 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 ked, the first a
2f390 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 rgument passed i
2f3a0 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 s a copy.** of t
2f3b0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
2f3c0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f nt to sqlite3_co
2f3d0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 llation_needed()
2f3e0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 or.** sqlite3_c
2f3f0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 ollation_needed1
2f400 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 6(). The second
2f410 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
2f420 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e database.** con
2f430 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 nection. The th
2f440 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ird argument is
2f450 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 one of [SQLITE_U
2f460 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 TF8], [SQLITE_UT
2f470 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 F16BE],.** or [S
2f480 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 QLITE_UTF16LE],
2f490 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d indicating the m
2f4a0 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f ost desirable fo
2f4b0 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 rm of the collat
2f4c0 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 ion.** sequence
2f4d0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 function require
2f4e0 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 d. The fourth p
2f4f0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 arameter is the
2f500 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 name of the.** r
2f510 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f equired collatio
2f520 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a n sequence.)^.**
2f530 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b .** The callback
2f540 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 function should
2f550 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64 65 register the de
2f560 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 sired collation
2f570 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 using.** [sqlite
2f580 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
2f590 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f on()], [sqlite3_
2f5a0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
2f5b0 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 16()], or.** [sq
2f5c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
2f5d0 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f lation_v2()]..*/
2f5e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
2f5f0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f sqlite3_collatio
2f600 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 n_needed(. sqli
2f610 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 te3*, . void*,
2f620 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a . void(*)(void*
2f630 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 ,sqlite3*,int eT
2f640 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 extRep,const cha
2f650 72 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 r*).);.SQLITE_AP
2f660 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f I int sqlite3_co
2f670 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 llation_needed16
2f680 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 (. sqlite3*, .
2f690 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a void*,. void(*
2f6a0 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a )(void*,sqlite3*
2f6b0 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f ,int eTextRep,co
2f6c0 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 nst void*).);..#
2f6d0 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41 53 ifdef SQLITE_HAS
2f6e0 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 _CODEC./*.** Spe
2f6f0 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 cify the key for
2f700 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 an encrypted da
2f710 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f tabase. This ro
2f720 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a utine should be.
2f730 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 ** called right
2f740 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 after sqlite3_op
2f750 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 en()..**.** The
2f760 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e code to implemen
2f770 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f t this API is no
2f780 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 t available in t
2f790 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 he public releas
2f7a0 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a e.** of SQLite..
2f7b0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
2f7c0 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 t sqlite3_key(.
2f7d0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
2f7e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2f7f0 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 /* Database to b
2f800 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 e rekeyed */. c
2f810 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c onst void *pKey,
2f820 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a int nKey /*
2f830 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a The key */.);..
2f840 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 /*.** Change the
2f850 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 key on an open
2f860 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 database. If th
2f870 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 e current databa
2f880 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 se is not.** enc
2f890 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 rypted, this rou
2f8a0 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 tine will encryp
2f8b0 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d t it. If pNew==
2f8c0 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 0 or nNew==0, th
2f8d0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 e.** database is
2f8e0 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a decrypted..**.*
2f8f0 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d * The code to im
2f900 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 plement this API
2f910 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c is not availabl
2f920 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 e in the public
2f930 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 release.** of SQ
2f940 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f Lite..*/.SQLITE_
2f950 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
2f960 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 rekey(. sqlite3
2f970 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
2f980 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 /* Datab
2f990 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 ase to be rekeye
2f9a0 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 d */. const voi
2f9b0 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 d *pKey, int nKe
2f9c0 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 y /* The new
2f9d0 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a key */.);../*.*
2f9e0 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63 * Specify the ac
2f9f0 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 tivation key for
2fa00 20 61 20 53 45 45 20 64 61 74 61 62 61 73 65 2e a SEE database.
2fa10 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 Unless .** act
2fa20 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 ivated, none of
2fa30 74 68 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73 the SEE routines
2fa40 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 53 will work..*/.S
2fa50 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
2fa60 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f qlite3_activate_
2fa70 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 see(. const cha
2fa80 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 r *zPassPhrase
2fa90 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 /* Activat
2faa0 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b ion phrase */.);
2fab0 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 .#endif..#ifdef
2fac0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 SQLITE_ENABLE_CE
2fad0 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 ROD./*.** Specif
2fae0 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e y the activation
2faf0 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44 key for a CEROD
2fb00 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 database. Unle
2fb10 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 ss .** activated
2fb20 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45 , none of the CE
2fb30 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c ROD routines wil
2fb40 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 l work..*/.SQLIT
2fb50 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 E_API void sqlit
2fb60 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65 72 6f e3_activate_cero
2fb70 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 d(. const char
2fb80 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20 *zPassPhrase
2fb90 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f /* Activatio
2fba0 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 n phrase */.);.#
2fbb0 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 endif../*.** CAP
2fbc0 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45 I3REF: Suspend E
2fbd0 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 xecution For A S
2fbe0 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 hort Time.**.**
2fbf0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 The sqlite3_slee
2fc00 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 p() function cau
2fc10 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 ses the current
2fc20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e thread to suspen
2fc30 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 d execution.** f
2fc40 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 or at least a nu
2fc50 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 mber of millisec
2fc60 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69 onds specified i
2fc70 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e n its parameter.
2fc80 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 .**.** If the op
2fc90 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 erating system d
2fca0 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 oes not support
2fcb0 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77 sleep requests w
2fcc0 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f ith.** milliseco
2fcd0 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 nd time resoluti
2fce0 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d on, then the tim
2fcf0 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 e will be rounde
2fd00 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e d up to.** the n
2fd10 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 earest second. T
2fd20 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c he number of mil
2fd30 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 liseconds of sle
2fd40 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 ep actually.** r
2fd50 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 equested from th
2fd60 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 e operating syst
2fd70 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a em is returned..
2fd80 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d **.** ^SQLite im
2fd90 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e plements this in
2fda0 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 terface by calli
2fdb0 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a ng the xSleep().
2fdc0 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 ** method of the
2fdd0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 default [sqlite
2fde0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 3_vfs] object.
2fdf0 49 66 20 74 68 65 20 78 53 6c 65 65 70 28 29 20 If the xSleep()
2fe00 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 method.** of the
2fe10 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 default VFS is
2fe20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 not implemented
2fe30 63 6f 72 72 65 63 74 6c 79 2c 20 6f 72 20 6e 6f correctly, or no
2fe40 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 74 t implemented at
2fe50 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e 20 74 68 .** all, then th
2fe60 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 e behavior of sq
2fe70 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 6d 61 lite3_sleep() ma
2fe80 79 20 64 65 76 69 61 74 65 20 66 72 6f 6d 20 74 y deviate from t
2fe90 68 65 20 64 65 73 63 72 69 70 74 69 6f 6e 0a 2a he description.*
2fea0 2a 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 * in the previou
2feb0 73 20 70 61 72 61 67 72 61 70 68 73 2e 0a 2a 2f s paragraphs..*/
2fec0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
2fed0 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e sqlite3_sleep(in
2fee0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
2fef0 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 REF: Name Of The
2ff00 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 Folder Holding
2ff10 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a Temporary Files.
2ff20 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 **.** ^(If this
2ff30 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 global variable
2ff40 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 is made to point
2ff50 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 to a string whi
2ff60 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d ch is.** the nam
2ff70 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 e of a folder (a
2ff80 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 .k.a. directory)
2ff90 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f , then all tempo
2ffa0 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 rary files.** cr
2ffb0 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 eated by SQLite
2ffc0 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69 when using a bui
2ffd0 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 lt-in [sqlite3_v
2ffe0 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c fs | VFS].** wil
2fff0 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 l be placed in t
30000 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e hat directory.)^
30010 20 20 5e 49 66 20 74 68 69 73 20 76 61 72 69 61 ^If this varia
30020 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c ble.** is a NULL
30030 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 pointer, then S
30040 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61 QLite performs a
30050 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 search for an a
30060 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 ppropriate.** te
30070 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72 mporary file dir
30080 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 ectory..**.** It
30090 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 is not safe to
300a0 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 read or modify t
300b0 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20 his variable in
300c0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a more than one.**
300d0 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69 6d thread at a tim
300e0 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61 e. It is not sa
300f0 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f fe to read or mo
30100 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 dify this variab
30110 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 le.** if a [data
30120 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
30130 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 61 is being used a
30140 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 t the same time
30150 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a in a separate.**
30160 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 thread..** It i
30170 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 s intended that
30180 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 this variable be
30190 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 set once.** as
301a0 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 part of process
301b0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 initialization a
301c0 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 nd before any SQ
301d0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a Lite interface.*
301e0 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 * routines have
301f0 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 been called and
30200 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 that this variab
30210 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e le remain unchan
30220 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 ged.** thereafte
30230 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 r..**.** ^The [t
30240 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 emp_store_direct
30250 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 ory pragma] may
30260 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 modify this vari
30270 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a able and cause.*
30280 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f * it to point to
30290 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 memory obtained
302a0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
302b0 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 alloc]. ^Furthe
302c0 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 rmore,.** the [t
302d0 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 emp_store_direct
302e0 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 ory pragma] alwa
302f0 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 ys assumes that
30300 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 any string.** th
30310 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 at this variable
30320 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65 points to is he
30330 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 ld in memory obt
30340 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b ained from .** [
30350 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 sqlite3_malloc]
30360 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d and the pragma m
30370 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72 ay attempt to fr
30380 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a ee that memory.*
30390 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 * using [sqlite3
303a0 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 _free]..** Hence
303b0 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61 62 , if this variab
303c0 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64 le is modified d
303d0 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20 irectly, either
303e0 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 it should be.**
303f0 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 made NULL or mad
30400 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 e to point to me
30410 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 mory obtained fr
30420 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
30430 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 oc].** or else t
30440 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74 he use of the [t
30450 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 emp_store_direct
30460 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 ory pragma] shou
30470 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a ld be avoided..*
30480 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c /.SQLITE_API SQL
30490 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 ITE_EXTERN char
304a0 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 *sqlite3_temp_di
304b0 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 rectory;../*.**
304c0 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 CAPI3REF: Test F
304d0 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d or Auto-Commit M
304e0 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ode.** KEYWORDS:
304f0 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 {autocommit mod
30500 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 e}.**.** ^The sq
30510 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f lite3_get_autoco
30520 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 mmit() interface
30530 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 returns non-zer
30540 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 o or.** zero if
30550 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 the given databa
30560 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
30570 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 or is not in au
30580 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a tocommit mode,.*
30590 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 * respectively.
305a0 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 ^Autocommit mod
305b0 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 e is on by defau
305c0 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d lt..** ^Autocomm
305d0 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 it mode is disab
305e0 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d led by a [BEGIN]
305f0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e statement..** ^
30600 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 Autocommit mode
30610 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 is re-enabled by
30620 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b a [COMMIT] or [
30630 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a ROLLBACK]..**.**
30640 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 If certain kind
30650 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 s of errors occu
30660 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 r on a statement
30670 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d within a multi-
30680 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 statement.** tra
30690 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 nsaction (errors
306a0 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 including [SQLI
306b0 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 TE_FULL], [SQLIT
306c0 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 E_IOERR],.** [SQ
306d0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 LITE_NOMEM], [SQ
306e0 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 LITE_BUSY], and
306f0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 [SQLITE_INTERRUP
30700 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 T]) then the.**
30710 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 transaction migh
30720 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b t be rolled back
30730 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 automatically.
30740 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f The only way to
30750 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 .** find out whe
30760 74 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f ther SQLite auto
30770 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 matically rolled
30780 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 back the transa
30790 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 ction after.** a
307a0 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 n error is to us
307b0 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e e this function.
307c0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 .**.** If anothe
307d0 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 r thread changes
307e0 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 the autocommit
307f0 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 status of the da
30800 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 tabase.** connec
30810 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 tion while this
30820 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 routine is runni
30830 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 ng, then the ret
30840 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 urn value.** is
30850 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 undefined..*/.SQ
30860 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
30870 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d ite3_get_autocom
30880 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a mit(sqlite3*);..
30890 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
308a0 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 73 Find The Databas
308b0 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 e Handle Of A Pr
308c0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 epared Statement
308d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
308e0 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e te3_db_handle in
308f0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
30900 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
30910 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 nnection] handle
30920 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b .** to which a [
30930 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
30940 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 5e 54 nt] belongs. ^T
30950 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
30960 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75 nection].** retu
30970 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
30980 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68 65 db_handle is the
30990 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 same [database
309a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 connection].** t
309b0 68 61 74 20 77 61 73 20 74 68 65 20 66 69 72 73 hat was the firs
309c0 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f t argument.** to
309d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 the [sqlite3_pr
309e0 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c epare_v2()] call
309f0 20 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 (or its variant
30a00 73 29 20 74 68 61 74 20 77 61 73 20 75 73 65 64 s) that was used
30a10 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68 to.** create th
30a20 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 e statement in t
30a30 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a he first place..
30a40 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 */.SQLITE_API sq
30a50 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 lite3 *sqlite3_d
30a60 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 b_handle(sqlite3
30a70 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 _stmt*);../*.**
30a80 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 74 CAPI3REF: Find t
30a90 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 65 64 he next prepared
30aa0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a statement.**.**
30ab0 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 ^This interface
30ac0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
30ad0 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20 5b er to the next [
30ae0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
30af0 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53 74 nt] after.** pSt
30b00 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 mt associated wi
30b10 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 th the [database
30b20 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62 connection] pDb
30b30 2e 20 20 5e 49 66 20 70 53 74 6d 74 20 69 73 20 . ^If pStmt is
30b40 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 NULL.** then thi
30b50 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 s interface retu
30b60 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
30b70 20 74 68 65 20 66 69 72 73 74 20 70 72 65 70 61 the first prepa
30b80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a red statement.**
30b90 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
30ba0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
30bb0 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 5e nnection pDb. ^
30bc0 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20 73 If no prepared s
30bd0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 tatement.** sati
30be0 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69 74 sfies the condit
30bf0 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f 75 ions of this rou
30c00 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e 73 tine, it returns
30c10 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 NULL..**.** The
30c20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
30c30 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44 ction] pointer D
30c40 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a in a call to.**
30c50 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 [sqlite3_next_s
30c60 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20 72 tmt(D,S)] must r
30c70 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20 efer to an open
30c80 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
30c90 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61 ection and in pa
30ca0 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f rticular must no
30cb0 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e t be a NULL poin
30cc0 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ter..*/.SQLITE_A
30cd0 50 49 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 PI sqlite3_stmt
30ce0 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 *sqlite3_next_st
30cf0 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c mt(sqlite3 *pDb,
30d00 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 sqlite3_stmt *p
30d10 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Stmt);../*.** CA
30d20 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 PI3REF: Commit A
30d30 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 nd Rollback Noti
30d40 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 fication Callbac
30d50 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 ks.**.** ^The sq
30d60 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f lite3_commit_hoo
30d70 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 k() interface re
30d80 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 gisters a callba
30d90 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 ck.** function t
30da0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 o be invoked whe
30db0 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 never a transact
30dc0 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c ion is [COMMIT |
30dd0 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 committed]..**
30de0 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 ^Any callback se
30df0 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 t by a previous
30e00 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
30e10 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a commit_hook().**
30e20 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 for the same da
30e30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
30e40 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e n is overridden.
30e50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
30e60 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 _rollback_hook()
30e70 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 interface regis
30e80 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a ters a callback.
30e90 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ** function to b
30ea0 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 e invoked whenev
30eb0 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e er a transaction
30ec0 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 is [ROLLBACK |
30ed0 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a rolled back]..**
30ee0 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 ^Any callback s
30ef0 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 et by a previous
30f00 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
30f10 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 _rollback_hook()
30f20 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 .** for the same
30f30 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
30f40 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 tion is overridd
30f50 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67 en..** ^The pArg
30f60 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 argument is pas
30f70 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 sed through to t
30f80 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 he callback..**
30f90 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b ^If the callback
30fa0 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f on a commit hoo
30fb0 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 k function retur
30fc0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 ns non-zero,.**
30fd0 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 then the commit
30fe0 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 is converted int
30ff0 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a o a rollback..**
31000 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
31010 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 _commit_hook(D,C
31020 2c 50 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f ,P) and sqlite3_
31030 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c rollback_hook(D,
31040 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a C,P) functions.*
31050 2a 20 72 65 74 75 72 6e 20 74 68 65 20 50 20 61 * return the P a
31060 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 rgument from the
31070 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f previous call o
31080 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 f the same funct
31090 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 ion.** on the sa
310a0 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e me [database con
310b0 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e nection] D, or N
310c0 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 ULL for.** the f
310d0 69 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 65 61 irst call for ea
310e0 63 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 ch function on D
310f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c ..**.** The call
31100 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 back implementat
31110 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 ion must not do
31120 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 anything that wi
31130 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 ll modify.** the
31140 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
31150 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 tion that invoke
31160 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 d the callback.
31170 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 Any actions.**
31180 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 to modify the da
31190 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
311a0 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 n must be deferr
311b0 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 ed until after t
311c0 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e he.** completion
311d0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
311e0 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 _step()] call th
311f0 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 at triggered the
31200 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f commit.** or ro
31210 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 llback hook in t
31220 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a he first place..
31230 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 ** Note that [sq
31240 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
31250 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
31260 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f _step()] both mo
31270 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 dify their.** da
31280 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
31290 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 ns for the meani
312a0 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 ng of "modify" i
312b0 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 n this paragraph
312c0 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65 ..**.** ^Registe
312d0 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 ring a NULL func
312e0 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 tion disables th
312f0 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a e callback..**.*
31300 2a 20 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d * ^When the comm
31310 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b it hook callback
31320 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
31330 20 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d zero, the [COMM
31340 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e IT].** operation
31350 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63 is allowed to c
31360 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 ontinue normally
31370 2e 20 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69 . ^If the commi
31380 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e t hook.** return
31390 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e s non-zero, then
313a0 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 the [COMMIT] is
313b0 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 converted into
313c0 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a a [ROLLBACK]..**
313d0 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 ^The rollback h
313e0 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f ook is invoked o
313f0 6e 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 n a rollback tha
31400 74 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 t results from a
31410 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 commit.** hook
31420 72 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 returning non-ze
31430 72 6f 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77 ro, just as it w
31440 6f 75 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79 ould be with any
31450 20 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e other rollback.
31460 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 .**.** ^For the
31470 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 purposes of this
31480 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 API, a transact
31490 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 ion is said to h
314a0 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c ave been.** roll
314b0 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 ed back if an ex
314c0 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b plicit "ROLLBACK
314d0 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 " statement is e
314e0 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 xecuted, or.** a
314f0 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 n error or const
31500 72 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 raint causes an
31510 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 implicit rollbac
31520 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e k to occur..** ^
31530 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c The rollback cal
31540 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 lback is not inv
31550 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 oked if a transa
31560 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f ction is.** auto
31570 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 matically rolled
31580 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 back because th
31590 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
315a0 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e ction is closed.
315b0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 .**.** See also
315c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 the [sqlite3_upd
315d0 61 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 ate_hook()] inte
315e0 72 66 61 63 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 rface..*/.SQLITE
315f0 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 _API void *sqlit
31600 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 e3_commit_hook(s
31610 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 qlite3*, int(*)(
31620 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a void*), void*);.
31630 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
31640 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 *sqlite3_rollbac
31650 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c k_hook(sqlite3*,
31660 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 void(*)(void *)
31670 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a , void*);../*.**
31680 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20 CAPI3REF: Data
31690 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 Change Notificat
316a0 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a ion Callbacks.**
316b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
316c0 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69 _update_hook() i
316d0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 nterface registe
316e0 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 rs a callback fu
316f0 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 nction.** with t
31700 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
31710 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66 nection] identif
31720 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 ied by the first
31730 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 argument.** to
31740 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 be invoked whene
31750 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 64 ver a row is upd
31760 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f ated, inserted o
31770 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 41 r deleted..** ^A
31780 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 ny callback set
31790 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 by a previous ca
317a0 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 ll to this funct
317b0 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 ion.** for the s
317c0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e ame database con
317d0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 nection is overr
317e0 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 idden..**.** ^Th
317f0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
31800 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 t is a pointer t
31810 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 o the function t
31820 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a o invoke when a.
31830 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 ** row is update
31840 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 d, inserted or d
31850 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 eleted..** ^The
31860 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
31870 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 o the callback i
31880 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 s a copy of the
31890 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a third argument.*
318a0 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 * to sqlite3_upd
318b0 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e ate_hook()..** ^
318c0 54 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 The second callb
318d0 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ack argument is
318e0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 one of [SQLITE_I
318f0 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f NSERT], [SQLITE_
31900 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b DELETE],.** or [
31910 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 20 SQLITE_UPDATE],
31920 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 depending on the
31930 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 operation that
31940 63 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62 caused the callb
31950 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 ack.** to be inv
31960 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 74 68 oked..** ^The th
31970 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61 ird and fourth a
31980 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 rguments to the
31990 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e callback contain
319a0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 pointers to the
319b0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 61 6e 64 .** database and
319c0 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 table name cont
319d0 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63 aining the affec
319e0 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 5e 54 68 65 ted row..** ^The
319f0 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 final callback
31a00 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
31a10 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 [rowid] of the
31a20 72 6f 77 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 row..** ^In the
31a30 63 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74 case of an updat
31a40 65 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 5b e, this is the [
31a50 72 6f 77 69 64 5d 20 61 66 74 65 72 20 74 68 65 rowid] after the
31a60 20 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c update takes pl
31a70 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 ace..**.** ^(The
31a80 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 update hook is
31a90 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e not invoked when
31aa0 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d internal system
31ab0 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d tables are.** m
31ac0 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71 odified (i.e. sq
31ad0 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 lite_master and
31ae0 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29 sqlite_sequence)
31af0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 .)^.**.** ^In th
31b00 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d e current implem
31b10 65 6e 74 61 74 69 6f 6e 2c 20 74 68 65 20 75 70 entation, the up
31b20 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 73 20 date hook.** is
31b30 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e not invoked when
31b40 20 64 75 70 6c 69 63 61 74 69 6f 6e 20 72 6f 77 duplication row
31b50 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 62 65 s are deleted be
31b60 63 61 75 73 65 20 6f 66 20 61 6e 0a 2a 2a 20 5b cause of an.** [
31b70 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 7c 20 4f 4e ON CONFLICT | ON
31b80 20 43 4f 4e 46 4c 49 43 54 20 52 45 50 4c 41 43 CONFLICT REPLAC
31b90 45 5d 20 63 6c 61 75 73 65 2e 20 20 5e 4e 6f 72 E] clause. ^Nor
31ba0 20 69 73 20 74 68 65 20 75 70 64 61 74 65 20 68 is the update h
31bb0 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 77 ook.** invoked w
31bc0 68 65 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c hen rows are del
31bd0 65 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b eted using the [
31be0 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a truncate optimiz
31bf0 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 65 ation]..** The e
31c00 78 63 65 70 74 69 6f 6e 73 20 64 65 66 69 6e 65 xceptions define
31c10 64 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 d in this paragr
31c20 61 70 68 20 6d 69 67 68 74 20 63 68 61 6e 67 65 aph might change
31c30 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 in a future.**
31c40 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 release of SQLit
31c50 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 e..**.** The upd
31c60 61 74 65 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65 ate hook impleme
31c70 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 ntation must not
31c80 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 do anything tha
31c90 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a t will modify.**
31ca0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
31cb0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e nnection that in
31cc0 76 6f 6b 65 64 20 74 68 65 20 75 70 64 61 74 65 voked the update
31cd0 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 61 63 74 69 hook. Any acti
31ce0 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 ons.** to modify
31cf0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
31d00 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 nnection must be
31d10 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 deferred until
31d20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d after the.** com
31d30 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b pletion of the [
31d40 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
31d50 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 call that trigge
31d60 72 65 64 20 74 68 65 20 75 70 64 61 74 65 20 68 red the update h
31d70 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ook..** Note tha
31d80 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 t [sqlite3_prepa
31d90 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 re_v2()] and [sq
31da0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f lite3_step()] bo
31db0 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a th modify their.
31dc0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ** database conn
31dd0 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 ections for the
31de0 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 meaning of "modi
31df0 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 fy" in this para
31e00 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 graph..**.** ^Th
31e10 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 e sqlite3_update
31e20 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e _hook(D,C,P) fun
31e30 63 74 69 6f 6e 0a 2a 2a 20 72 65 74 75 72 6e 73 ction.** returns
31e40 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 the P argument
31e50 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 from the previou
31e60 73 20 63 61 6c 6c 0a 2a 2a 20 6f 6e 20 74 68 65 s call.** on the
31e70 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 same [database
31e80 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f connection] D, o
31e90 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 r NULL for.** th
31ea0 65 20 66 69 72 73 74 20 63 61 6c 6c 20 6f 6e 20 e first call on
31eb0 44 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 D..**.** See als
31ec0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 o the [sqlite3_c
31ed0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 61 6e ommit_hook()] an
31ee0 64 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 d [sqlite3_rollb
31ef0 61 63 6b 5f 68 6f 6f 6b 28 29 5d 0a 2a 2a 20 69 ack_hook()].** i
31f00 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2f 0a 53 51 nterfaces..*/.SQ
31f10 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 LITE_API void *s
31f20 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f qlite3_update_ho
31f30 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 ok(. sqlite3*,
31f40 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 . void(*)(void
31f50 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 *,int ,char cons
31f60 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a t *,char const *
31f70 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c ,sqlite3_int64),
31f80 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a . void*.);../*.
31f90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 ** CAPI3REF: Ena
31fa0 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 ble Or Disable S
31fb0 68 61 72 65 64 20 50 61 67 65 72 20 43 61 63 68 hared Pager Cach
31fc0 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b e.** KEYWORDS: {
31fd0 73 68 61 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a shared cache}.**
31fe0 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 .** ^(This routi
31ff0 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 ne enables or di
32000 73 61 62 6c 65 73 20 74 68 65 20 73 68 61 72 69 sables the shari
32010 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 ng of the databa
32020 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 se cache.** and
32030 73 63 68 65 6d 61 20 64 61 74 61 20 73 74 72 75 schema data stru
32040 63 74 75 72 65 73 20 62 65 74 77 65 65 6e 20 5b ctures between [
32050 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
32060 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e ion | connection
32070 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d s].** to the sam
32080 65 20 64 61 74 61 62 61 73 65 2e 20 53 68 61 72 e database. Shar
32090 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69 ing is enabled i
320a0 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 f the argument i
320b0 73 20 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 s true.** and di
320c0 73 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 sabled if the ar
320d0 67 75 6d 65 6e 74 20 69 73 20 66 61 6c 73 65 2e gument is false.
320e0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 )^.**.** ^Cache
320f0 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c sharing is enabl
32100 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 ed and disabled
32110 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20 70 72 for an entire pr
32120 6f 63 65 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69 ocess..** This i
32130 73 20 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66 s a change as of
32140 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
32150 33 2e 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 3.5.0. In prior
32160 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
32170 74 65 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 te,.** sharing w
32180 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 as enabled or di
32190 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20 sabled for each
321a0 74 68 72 65 61 64 20 73 65 70 61 72 61 74 65 6c thread separatel
321b0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 y..**.** ^(The c
321c0 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 ache sharing mod
321d0 65 20 73 65 74 20 62 79 20 74 68 69 73 20 69 6e e set by this in
321e0 74 65 72 66 61 63 65 20 65 66 66 65 63 74 73 20 terface effects
321f0 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a all subsequent.*
32200 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 * calls to [sqli
32210 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 te3_open()], [sq
32220 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d lite3_open_v2()]
32230 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f , and [sqlite3_o
32240 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 pen16()]..** Exi
32250 73 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 63 sting database c
32260 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 onnections conti
32270 6e 75 65 20 75 73 65 20 74 68 65 20 73 68 61 72 nue use the shar
32280 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 ing mode.** that
32290 20 77 61 73 20 69 6e 20 65 66 66 65 63 74 20 61 was in effect a
322a0 74 20 74 68 65 20 74 69 6d 65 20 74 68 65 79 20 t the time they
322b0 77 65 72 65 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a were opened.)^.*
322c0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 *.** ^(This rout
322d0 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ine returns [SQL
322e0 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 ITE_OK] if share
322f0 64 20 63 61 63 68 65 20 77 61 73 20 65 6e 61 62 d cache was enab
32300 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a led or disabled.
32310 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e ** successfully.
32320 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 An [error code
32330 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74 ] is returned ot
32340 68 65 72 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a herwise.)^.**.**
32350 20 5e 53 68 61 72 65 64 20 63 61 63 68 65 20 69 ^Shared cache i
32360 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 s disabled by de
32370 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69 73 20 fault. But this
32380 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a might change in.
32390 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 ** future releas
323a0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 es of SQLite. A
323b0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 pplications that
323c0 20 63 61 72 65 20 61 62 6f 75 74 20 73 68 61 72 care about shar
323d0 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74 ed.** cache sett
323e0 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69 ing should set i
323f0 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a t explicitly..**
32400 0a 2a 2a 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b .** See Also: [
32410 53 51 4c 69 74 65 20 53 68 61 72 65 64 2d 43 61 SQLite Shared-Ca
32420 63 68 65 20 4d 6f 64 65 5d 0a 2a 2f 0a 53 51 4c che Mode].*/.SQL
32430 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
32440 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 te3_enable_share
32450 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f d_cache(int);../
32460 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 *.** CAPI3REF: A
32470 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48 ttempt To Free H
32480 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a eap Memory.**.**
32490 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 ^The sqlite3_re
324a0 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 lease_memory() i
324b0 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 nterface attempt
324c0 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65 s to free N byte
324d0 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d s.** of heap mem
324e0 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 ory by deallocat
324f0 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 ing non-essentia
32500 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 l memory allocat
32510 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 ions.** held by
32520 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 the database lib
32530 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75 rary. Memory u
32540 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74 sed to cache dat
32550 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 abase.** pages t
32560 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 o improve perfor
32570 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d mance is an exam
32580 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e ple of non-essen
32590 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 tial memory..**
325a0 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 ^sqlite3_release
325b0 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e _memory() return
325c0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
325d0 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 bytes actually f
325e0 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d reed,.** which m
325f0 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 ight be more or
32600 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d less than the am
32610 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a ount requested..
32620 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
32630 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 release_memory()
32640 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 6e 6f routine is a no
32650 2d 6f 70 20 72 65 74 75 72 6e 69 6e 67 20 7a 65 -op returning ze
32660 72 6f 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 ro.** if SQLite
32670 69 73 20 6e 6f 74 20 63 6f 6d 70 69 6c 65 64 20 is not compiled
32680 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41 with [SQLITE_ENA
32690 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 BLE_MEMORY_MANAG
326a0 45 4d 45 4e 54 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 EMENT]..*/.SQLIT
326b0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
326c0 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 3_release_memory
326d0 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 (int);../*.** CA
326e0 50 49 33 52 45 46 3a 20 49 6d 70 6f 73 65 20 41 PI3REF: Impose A
326f0 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 Limit On Heap S
32700 69 7a 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ize.**.** ^The s
32710 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 qlite3_soft_heap
32720 5f 6c 69 6d 69 74 36 34 28 29 20 69 6e 74 65 72 _limit64() inter
32730 66 61 63 65 20 73 65 74 73 20 61 6e 64 2f 6f 72 face sets and/or
32740 20 71 75 65 72 69 65 73 20 74 68 65 0a 2a 2a 20 queries the.**
32750 73 6f 66 74 20 6c 69 6d 69 74 20 6f 6e 20 74 68 soft limit on th
32760 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 e amount of heap
32770 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 memory that may
32780 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 be allocated by
32790 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 5e 53 51 4c SQLite..** ^SQL
327a0 69 74 65 20 73 74 72 69 76 65 73 20 74 6f 20 6b ite strives to k
327b0 65 65 70 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 eep heap memory
327c0 75 74 69 6c 69 7a 61 74 69 6f 6e 20 62 65 6c 6f utilization belo
327d0 77 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 0a w the soft heap.
327e0 2a 2a 20 6c 69 6d 69 74 20 62 79 20 72 65 64 75 ** limit by redu
327f0 63 69 6e 67 20 74 68 65 20 6e 75 6d 62 65 72 20 cing the number
32800 6f 66 20 70 61 67 65 73 20 68 65 6c 64 20 69 6e of pages held in
32810 20 74 68 65 20 70 61 67 65 20 63 61 63 68 65 0a the page cache.
32820 2a 2a 20 61 73 20 68 65 61 70 20 6d 65 6d 6f 72 ** as heap memor
32830 79 20 75 73 61 67 65 73 20 61 70 70 72 6f 61 63 y usages approac
32840 68 65 73 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a hes the limit..*
32850 2a 20 5e 54 68 65 20 73 6f 66 74 20 68 65 61 70 * ^The soft heap
32860 20 6c 69 6d 69 74 20 69 73 20 22 73 6f 66 74 22 limit is "soft"
32870 20 62 65 63 61 75 73 65 20 65 76 65 6e 20 74 68 because even th
32880 6f 75 67 68 20 53 51 4c 69 74 65 20 73 74 72 69 ough SQLite stri
32890 76 65 73 20 74 6f 20 73 74 61 79 0a 2a 2a 20 62 ves to stay.** b
328a0 65 6c 6f 77 20 74 68 65 20 6c 69 6d 69 74 2c 20 elow the limit,
328b0 69 74 20 77 69 6c 6c 20 65 78 63 65 65 64 20 74 it will exceed t
328c0 68 65 20 6c 69 6d 69 74 20 72 61 74 68 65 72 20 he limit rather
328d0 74 68 61 6e 20 67 65 6e 65 72 61 74 65 0a 2a 2a than generate.**
328e0 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 an [SQLITE_NOME
328f0 4d 5d 20 65 72 72 6f 72 2e 20 20 49 6e 20 6f 74 M] error. In ot
32900 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 73 her words, the s
32910 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 0a oft heap limit .
32920 2a 2a 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f ** is advisory o
32930 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 nly..**.** ^The
32940 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f return value fro
32950 6d 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 m sqlite3_soft_h
32960 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20 69 73 eap_limit64() is
32970 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 the size of.**
32980 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 the soft heap li
32990 6d 69 74 20 70 72 69 6f 72 20 74 6f 20 74 68 65 mit prior to the
329a0 20 63 61 6c 6c 2e 20 20 5e 49 66 20 74 68 65 20 call. ^If the
329b0 61 72 67 75 6d 65 6e 74 20 4e 20 69 73 20 6e 65 argument N is ne
329c0 67 61 74 69 76 65 0a 2a 2a 20 74 68 65 6e 20 6e gative.** then n
329d0 6f 20 63 68 61 6e 67 65 20 69 73 20 6d 61 64 65 o change is made
329e0 20 74 6f 20 74 68 65 20 73 6f 66 74 20 68 65 61 to the soft hea
329f0 70 20 6c 69 6d 69 74 2e 20 20 48 65 6e 63 65 2c p limit. Hence,
32a00 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 the current.**
32a10 73 69 7a 65 20 6f 66 20 74 68 65 20 73 6f 66 74 size of the soft
32a20 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61 6e 20 heap limit can
32a30 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 be determined by
32a40 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c invoking.** sql
32a50 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c ite3_soft_heap_l
32a60 69 6d 69 74 36 34 28 29 20 77 69 74 68 20 61 20 imit64() with a
32a70 6e 65 67 61 74 69 76 65 20 61 72 67 75 6d 65 6e negative argumen
32a80 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 t..**.** ^If the
32a90 20 61 72 67 75 6d 65 6e 74 20 4e 20 69 73 20 7a argument N is z
32aa0 65 72 6f 20 74 68 65 6e 20 74 68 65 20 73 6f 66 ero then the sof
32ab0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 t heap limit is
32ac0 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 disabled..**.**
32ad0 5e 28 54 68 65 20 73 6f 66 74 20 68 65 61 70 20 ^(The soft heap
32ae0 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 65 6e 66 limit is not enf
32af0 6f 72 63 65 64 20 69 6e 20 74 68 65 20 63 75 72 orced in the cur
32b00 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 rent implementat
32b10 69 6f 6e 0a 2a 2a 20 69 66 20 6f 6e 65 20 6f 72 ion.** if one or
32b20 20 6d 6f 72 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 more of followi
32b30 6e 67 20 63 6f 6e 64 69 74 69 6f 6e 73 20 61 72 ng conditions ar
32b40 65 20 74 72 75 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 e true:.**.** <u
32b50 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 73 l>.** <li> The s
32b60 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 oft heap limit i
32b70 73 20 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a s set to zero..*
32b80 2a 20 3c 6c 69 3e 20 4d 65 6d 6f 72 79 20 61 63 * <li> Memory ac
32b90 63 6f 75 6e 74 69 6e 67 20 69 73 20 64 69 73 61 counting is disa
32ba0 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 6f 6d bled using a com
32bb0 62 69 6e 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a bination of the.
32bc0 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 ** [sqlite3
32bd0 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 _config]([SQLITE
32be0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 _CONFIG_MEMSTATU
32bf0 53 5d 2c 2e 2e 2e 29 20 73 74 61 72 74 2d 74 69 S],...) start-ti
32c00 6d 65 20 6f 70 74 69 6f 6e 20 61 6e 64 0a 2a 2a me option and.**
32c10 20 20 20 20 20 20 74 68 65 20 5b 53 51 4c 49 54 the [SQLIT
32c20 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 E_DEFAULT_MEMSTA
32c30 54 55 53 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d TUS] compile-tim
32c40 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 e option..** <li
32c50 3e 20 41 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 > An alternative
32c60 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c page cache impl
32c70 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 73 70 ementation is sp
32c80 65 63 69 66 69 65 64 20 75 73 69 6e 67 0a 2a 2a ecified using.**
32c90 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 [sqlite3_c
32ca0 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 onfig]([SQLITE_C
32cb0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 2c 2e 2e ONFIG_PCACHE],..
32cc0 2e 29 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 .)..** <li> The
32cd0 70 61 67 65 20 63 61 63 68 65 20 61 6c 6c 6f 63 page cache alloc
32ce0 61 74 65 73 20 66 72 6f 6d 20 69 74 73 20 6f 77 ates from its ow
32cf0 6e 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 20 73 75 n memory pool su
32d00 70 70 6c 69 65 64 0a 2a 2a 20 20 20 20 20 20 62 pplied.** b
32d10 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 y [sqlite3_confi
32d20 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 g]([SQLITE_CONFI
32d30 47 5f 50 41 47 45 43 41 43 48 45 5d 2c 2e 2e 2e G_PAGECACHE],...
32d40 29 20 72 61 74 68 65 72 20 74 68 61 6e 0a 2a 2a ) rather than.**
32d50 20 20 20 20 20 20 66 72 6f 6d 20 74 68 65 20 68 from the h
32d60 65 61 70 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a eap..** </ul>)^.
32d70 2a 2a 0a 2a 2a 20 42 65 67 69 6e 6e 69 6e 67 20 **.** Beginning
32d80 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73 with SQLite vers
32d90 69 6f 6e 20 33 2e 37 2e 33 2c 20 74 68 65 20 73 ion 3.7.3, the s
32da0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 oft heap limit i
32db0 73 20 65 6e 66 6f 72 63 65 64 0a 2a 2a 20 72 65 s enforced.** re
32dc0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 gardless of whet
32dd0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b her or not the [
32de0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 SQLITE_ENABLE_ME
32df0 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d MORY_MANAGEMENT]
32e00 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 .** compile-time
32e10 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b option is invok
32e20 65 64 2e 20 20 57 69 74 68 20 5b 53 51 4c 49 54 ed. With [SQLIT
32e30 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f E_ENABLE_MEMORY_
32e40 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c 0a 2a 2a 20 MANAGEMENT],.**
32e50 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 the soft heap li
32e60 6d 69 74 20 69 73 20 65 6e 66 6f 72 63 65 64 20 mit is enforced
32e70 6f 6e 20 65 76 65 72 79 20 6d 65 6d 6f 72 79 20 on every memory
32e80 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 57 69 74 allocation. Wit
32e90 68 6f 75 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f hout.** [SQLITE_
32ea0 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 ENABLE_MEMORY_MA
32eb0 4e 41 47 45 4d 45 4e 54 5d 2c 20 74 68 65 20 73 NAGEMENT], the s
32ec0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 oft heap limit i
32ed0 73 20 6f 6e 6c 79 20 65 6e 66 6f 72 63 65 64 0a s only enforced.
32ee0 2a 2a 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 ** when memory i
32ef0 73 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 74 s allocated by t
32f00 68 65 20 70 61 67 65 20 63 61 63 68 65 2e 20 20 he page cache.
32f10 54 65 73 74 69 6e 67 20 73 75 67 67 65 73 74 73 Testing suggests
32f20 20 74 68 61 74 20 62 65 63 61 75 73 65 0a 2a 2a that because.**
32f30 20 74 68 65 20 70 61 67 65 20 63 61 63 68 65 20 the page cache
32f40 69 73 20 74 68 65 20 70 72 65 64 6f 6d 69 6e 61 is the predomina
32f50 74 65 20 6d 65 6d 6f 72 79 20 75 73 65 72 20 69 te memory user i
32f60 6e 20 53 51 4c 69 74 65 2c 20 6d 6f 73 74 0a 2a n SQLite, most.*
32f70 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 * applications w
32f80 69 6c 6c 20 61 63 68 69 65 76 65 20 61 64 65 71 ill achieve adeq
32f90 75 61 74 65 20 73 6f 66 74 20 68 65 61 70 20 6c uate soft heap l
32fa0 69 6d 69 74 20 65 6e 66 6f 72 63 65 6d 65 6e 74 imit enforcement
32fb0 20 77 69 74 68 6f 75 74 0a 2a 2a 20 74 68 65 20 without.** the
32fc0 75 73 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45 use of [SQLITE_E
32fd0 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e NABLE_MEMORY_MAN
32fe0 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 AGEMENT]..**.**
32ff0 54 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 The circumstance
33000 73 20 75 6e 64 65 72 20 77 68 69 63 68 20 53 51 s under which SQ
33010 4c 69 74 65 20 77 69 6c 6c 20 65 6e 66 6f 72 63 Lite will enforc
33020 65 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 e the soft heap
33030 6c 69 6d 69 74 20 6d 61 79 0a 2a 2a 20 63 68 61 limit may.** cha
33040 6e 67 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 nges in future r
33050 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 eleases of SQLit
33060 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 e..*/.SQLITE_API
33070 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 sqlite3_int64 s
33080 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 qlite3_soft_heap
33090 5f 6c 69 6d 69 74 36 34 28 73 71 6c 69 74 65 33 _limit64(sqlite3
330a0 5f 69 6e 74 36 34 20 4e 29 3b 0a 0a 2f 2a 0a 2a _int64 N);../*.*
330b0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 * CAPI3REF: Depr
330c0 65 63 61 74 65 64 20 53 6f 66 74 20 48 65 61 70 ecated Soft Heap
330d0 20 4c 69 6d 69 74 20 49 6e 74 65 72 66 61 63 65 Limit Interface
330e0 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a .** DEPRECATED.*
330f0 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 64 *.** This is a d
33100 65 70 72 65 63 61 74 65 64 20 76 65 72 73 69 6f eprecated versio
33110 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 n of the [sqlite
33120 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 3_soft_heap_limi
33130 74 36 34 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 t64()].** interf
33140 61 63 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 ace. This routi
33150 6e 65 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 ne is provided f
33160 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f or historical co
33170 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 6f mpatibility.** o
33180 6e 6c 79 2e 20 20 41 6c 6c 20 6e 65 77 20 61 70 nly. All new ap
33190 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c plications shoul
331a0 64 20 75 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 d use the.** [sq
331b0 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f lite3_soft_heap_
331c0 6c 69 6d 69 74 36 34 28 29 5d 20 69 6e 74 65 72 limit64()] inter
331d0 66 61 63 65 20 72 61 74 68 65 72 20 74 68 61 6e face rather than
331e0 20 74 68 69 73 20 6f 6e 65 2e 0a 2a 2f 0a 53 51 this one..*/.SQ
331f0 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
33200 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 DEPRECATED void
33210 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 sqlite3_soft_hea
33220 70 5f 6c 69 6d 69 74 28 69 6e 74 20 4e 29 3b 0a p_limit(int N);.
33230 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
33240 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61 64 61 : Extract Metada
33250 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d ta About A Colum
33260 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a 2a 0a n Of A Table.**.
33270 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 ** ^This routine
33280 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64 61 74 returns metadat
33290 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69 66 a about a specif
332a0 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 ic column of a s
332b0 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74 61 62 pecific.** datab
332c0 61 73 65 20 74 61 62 6c 65 20 61 63 63 65 73 73 ase table access
332d0 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 5b ible using the [
332e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
332f0 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 70 ion] handle.** p
33300 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 assed as the fir
33310 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 st function argu
33320 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ment..**.** ^The
33330 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 column is ident
33340 69 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63 ified by the sec
33350 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66 ond, third and f
33360 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 ourth parameters
33370 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 to.** this func
33380 74 69 6f 6e 2e 20 5e 54 68 65 20 73 65 63 6f 6e tion. ^The secon
33390 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 65 d parameter is e
333a0 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f ither the name o
333b0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a f the database.*
333c0 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 * (i.e. "main",
333d0 22 74 65 6d 70 22 2c 20 6f 72 20 61 6e 20 61 74 "temp", or an at
333e0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 29 tached database)
333f0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 containing the
33400 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 specified.** tab
33410 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 5e 49 66 20 le or NULL. ^If
33420 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e it is NULL, then
33430 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64 61 all attached da
33440 74 61 62 61 73 65 73 20 61 72 65 20 73 65 61 72 tabases are sear
33450 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 ched.** for the
33460 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 table using the
33470 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 75 same algorithm u
33480 73 65 64 20 62 79 20 74 68 65 20 64 61 74 61 62 sed by the datab
33490 61 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a ase engine to.**
334a0 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 resolve unquali
334b0 66 69 65 64 20 74 61 62 6c 65 20 72 65 66 65 72 fied table refer
334c0 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ences..**.** ^Th
334d0 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 e third and four
334e0 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f th parameters to
334f0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 61 this function a
33500 72 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e 64 re the table and
33510 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 column.** name
33520 6f 66 20 74 68 65 20 64 65 73 69 72 65 64 20 63 of the desired c
33530 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69 76 olumn, respectiv
33540 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66 20 ely. Neither of
33550 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 these parameters
33560 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e .** may be NULL.
33570 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61 64 61 74 61 .**.** ^Metadata
33580 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 is returned by
33590 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20 6d writing to the m
335a0 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20 emory locations
335b0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 35 74 passed as the 5t
335c0 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65 71 75 h.** and subsequ
335d0 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 ent parameters t
335e0 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e o this function.
335f0 20 5e 41 6e 79 20 6f 66 20 74 68 65 73 65 20 61 ^Any of these a
33600 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 0a rguments may be.
33610 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 ** NULL, in whic
33620 68 20 63 61 73 65 20 74 68 65 20 63 6f 72 72 65 h case the corre
33630 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74 sponding element
33640 20 6f 66 20 6d 65 74 61 64 61 74 61 20 69 73 20 of metadata is
33650 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e omitted..**.** ^
33660 28 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a (<blockquote>.**
33670 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 <table border="
33680 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 1">.** <tr><th>
33690 50 61 72 61 6d 65 74 65 72 20 3c 74 68 3e 20 4f Parameter <th> O
336a0 75 74 70 75 74 3c 62 72 3e 54 79 70 65 20 3c 74 utput<br>Type <t
336b0 68 3e 20 20 44 65 73 63 72 69 70 74 69 6f 6e 0a h> Description.
336c0 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 35 **.** <tr><td> 5
336d0 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 th <td> const ch
336e0 61 72 2a 20 3c 74 64 3e 20 44 61 74 61 20 74 79 ar* <td> Data ty
336f0 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 36 pe.** <tr><td> 6
33700 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 th <td> const ch
33710 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20 6f 66 ar* <td> Name of
33720 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 default collati
33730 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a 20 3c on sequence.** <
33740 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74 64 3e tr><td> 7th <td>
33750 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 int <td
33760 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e > True if column
33770 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 has a NOT NULL
33780 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 3c 74 constraint.** <t
33790 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64 3e 20 r><td> 8th <td>
337a0 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e int <td>
337b0 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 True if column
337c0 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 50 is part of the P
337d0 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 3c 74 RIMARY KEY.** <t
337e0 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64 3e 20 r><td> 9th <td>
337f0 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e int <td>
33800 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 True if column
33810 69 73 20 5b 41 55 54 4f 49 4e 43 52 45 4d 45 4e is [AUTOINCREMEN
33820 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a T].** </table>.*
33830 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 * </blockquote>)
33840 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d ^.**.** ^The mem
33850 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 ory pointed to b
33860 79 20 74 68 65 20 63 68 61 72 61 63 74 65 72 20 y the character
33870 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 pointers returne
33880 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64 65 63 d for the.** dec
33890 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61 6e laration type an
338a0 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 d collation sequ
338b0 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f 6e ence is valid on
338c0 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 ly until the nex
338d0 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79 t.** call to any
338e0 20 53 51 4c 69 74 65 20 41 50 49 20 66 75 6e 63 SQLite API func
338f0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 tion..**.** ^If
33900 74 68 65 20 73 70 65 63 69 66 69 65 64 20 74 61 the specified ta
33910 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79 20 ble is actually
33920 61 20 76 69 65 77 2c 20 61 6e 20 5b 65 72 72 6f a view, an [erro
33930 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 r code] is retur
33940 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 ned..**.** ^If t
33950 68 65 20 73 70 65 63 69 66 69 65 64 20 63 6f 6c he specified col
33960 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 2c 20 umn is "rowid",
33970 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 69 64 "oid" or "_rowid
33980 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b 49 4e _" and an.** [IN
33990 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 TEGER PRIMARY KE
339a0 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65 Y] column has be
339b0 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 en explicitly de
339c0 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 68 65 clared, then the
339d0 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d output.** param
339e0 65 74 65 72 73 20 61 72 65 20 73 65 74 20 66 6f eters are set fo
339f0 72 20 74 68 65 20 65 78 70 6c 69 63 69 74 6c 79 r the explicitly
33a00 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e declared column
33a10 2e 20 5e 28 49 66 20 74 68 65 72 65 20 69 73 20 . ^(If there is
33a20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79 no.** explicitly
33a30 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54 45 47 declared [INTEG
33a40 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 ER PRIMARY KEY]
33a50 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65 column, then the
33a60 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d output.** param
33a70 65 74 65 72 73 20 61 72 65 20 73 65 74 20 61 73 eters are set as
33a80 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 follows:.**.**
33a90 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74 <pre>.** dat
33aa0 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45 52 a type: "INTEGER
33ab0 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69 ".** collati
33ac0 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42 49 on sequence: "BI
33ad0 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 NARY".** not
33ae0 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 null: 0.**
33af0 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a primary key: 1.*
33b00 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72 65 * auto incre
33b10 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 ment: 0.** </pre
33b20 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 >)^.**.** ^(This
33b30 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f function may lo
33b40 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 ad one or more s
33b50 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 chemas from data
33b60 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20 61 base files. If a
33b70 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 n.** error occur
33b80 73 20 64 75 72 69 6e 67 20 74 68 69 73 20 70 72 s during this pr
33b90 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68 65 ocess, or if the
33ba0 20 72 65 71 75 65 73 74 65 64 20 74 61 62 6c 65 requested table
33bb0 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 or column.** ca
33bc0 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 nnot be found, a
33bd0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 n [error code] i
33be0 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 61 s returned and a
33bf0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 n error message
33c00 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65 20 5b left.** in the [
33c10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
33c20 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65 74 72 ion] (to be retr
33c30 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c 69 ieved using sqli
33c40 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 29 5e te3_errmsg()).)^
33c50 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41 50 49 .**.** ^This API
33c60 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 is only availab
33c70 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 le if the librar
33c80 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 y was compiled w
33c90 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 ith the.** [SQLI
33ca0 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e TE_ENABLE_COLUMN
33cb0 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 _METADATA] C-pre
33cc0 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c processor symbol
33cd0 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c defined..*/.SQL
33ce0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
33cf0 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e te3_table_column
33d00 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c _metadata(. sql
33d10 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
33d20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e /* Conn
33d30 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f ection handle */
33d40 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
33d50 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f DbName, /
33d60 2a 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20 * Database name
33d70 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e or NULL */. con
33d80 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e st char *zTableN
33d90 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c ame, /* Tabl
33da0 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 e name */. cons
33db0 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e t char *zColumnN
33dc0 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d ame, /* Colum
33dd0 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 n name */. char
33de0 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 const **pzDataT
33df0 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 ype, /* OUTPU
33e00 54 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74 61 T: Declared data
33e10 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 type */. char
33e20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 const **pzCollSe
33e30 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 q, /* OUTPUT
33e40 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 : Collation sequ
33e50 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 ence name */. i
33e60 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 nt *pNotNull,
33e70 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 /* OU
33e80 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f TPUT: True if NO
33e90 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e T NULL constrain
33ea0 74 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e t exists */. in
33eb0 74 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 t *pPrimaryKey,
33ec0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 /* OUT
33ed0 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c PUT: True if col
33ee0 75 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a umn part of PK *
33ef0 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e /. int *pAutoin
33f00 63 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 c
33f10 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 /* OUTPUT: True
33f20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74 if column is aut
33f30 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 o-increment */.)
33f40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
33f50 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e F: Load An Exten
33f60 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 sion.**.** ^This
33f70 20 69 6e 74 65 72 66 61 63 65 20 6c 6f 61 64 73 interface loads
33f80 20 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e an SQLite exten
33f90 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 66 72 6f sion library fro
33fa0 6d 20 74 68 65 20 6e 61 6d 65 64 20 66 69 6c 65 m the named file
33fb0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
33fc0 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 ite3_load_extens
33fd0 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 ion() interface
33fe0 61 74 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61 64 attempts to load
33ff0 20 61 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 65 78 an.** SQLite ex
34000 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 tension library
34010 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 65 contained in the
34020 20 66 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a 0a file zFile..**.
34030 2a 2a 20 5e 54 68 65 20 65 6e 74 72 79 20 70 6f ** ^The entry po
34040 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e 0a 2a 2a int is zProc..**
34050 20 5e 7a 50 72 6f 63 20 6d 61 79 20 62 65 20 30 ^zProc may be 0
34060 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 , in which case
34070 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
34080 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 64 entry point.** d
34090 65 66 61 75 6c 74 73 20 74 6f 20 22 73 71 6c 69 efaults to "sqli
340a0 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e te3_extension_in
340b0 69 74 22 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c it"..** ^The sql
340c0 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 ite3_load_extens
340d0 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 ion() interface
340e0 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 returns.** [SQLI
340f0 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 TE_OK] on succes
34100 73 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52 s and [SQLITE_ER
34110 52 4f 52 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e ROR] if somethin
34120 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a g goes wrong..**
34130 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 ^If an error oc
34140 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72 4d 73 curs and pzErrMs
34150 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68 65 6e g is not 0, then
34160 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
34170 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 _load_extension(
34180 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 )] interface sha
34190 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a ll attempt to.**
341a0 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 67 20 fill *pzErrMsg
341b0 77 69 74 68 20 65 72 72 6f 72 20 6d 65 73 73 61 with error messa
341c0 67 65 20 74 65 78 74 20 73 74 6f 72 65 64 20 69 ge text stored i
341d0 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 6f 62 74 61 n memory.** obta
341e0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 ined from [sqlit
341f0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 54 68 e3_malloc()]. Th
34200 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 e calling functi
34210 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 66 72 65 on.** should fre
34220 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 20 62 79 e this memory by
34230 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
34240 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 3_free()]..**.**
34250 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 ^Extension load
34260 69 6e 67 20 6d 75 73 74 20 62 65 20 65 6e 61 62 ing must be enab
34270 6c 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 led using.** [sq
34280 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 lite3_enable_loa
34290 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 d_extension()] p
342a0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 rior to calling
342b0 74 68 69 73 20 41 50 49 2c 0a 2a 2a 20 6f 74 68 this API,.** oth
342c0 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 erwise an error
342d0 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 will be returned
342e0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
342f0 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65 6e the [load_exten
34300 73 69 6f 6e 28 29 20 53 51 4c 20 66 75 6e 63 74 sion() SQL funct
34310 69 6f 6e 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f ion]..*/.SQLITE_
34320 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
34330 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a load_extension(.
34340 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
34350 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 /* Load
34360 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e the extension in
34370 74 6f 20 74 68 69 73 20 64 61 74 61 62 61 73 65 to this database
34380 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 connection */.
34390 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 const char *zFi
343a0 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f le, /* Name o
343b0 66 20 74 68 65 20 73 68 61 72 65 64 20 6c 69 62 f the shared lib
343c0 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 rary containing
343d0 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 extension */. c
343e0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 onst char *zProc
343f0 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f , /* Entry po
34400 69 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66 72 int. Derived fr
34410 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f om zFile if 0 */
34420 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d . char **pzErrM
34430 73 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20 sg /* Put
34440 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65 error message he
34450 72 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 re if not 0 */.)
34460 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
34470 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 F: Enable Or Dis
34480 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c able Extension L
34490 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f oading.**.** ^So
344a0 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 as not to open
344b0 73 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69 security holes i
344c0 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74 n older applicat
344d0 69 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a ions that are.**
344e0 20 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64 unprepared to d
344f0 65 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69 eal with extensi
34500 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 on loading, and
34510 61 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 as a means of di
34520 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e sabling.** exten
34530 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 sion loading whi
34540 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73 le evaluating us
34550 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 er-entered SQL,
34560 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 the following AP
34570 49 0a 2a 2a 20 69 73 20 70 72 6f 76 69 64 65 64 I.** is provided
34580 20 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71 to turn the [sq
34590 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e lite3_load_exten
345a0 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 sion()] mechanis
345b0 6d 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a m on and off..**
345c0 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c .** ^Extension l
345d0 6f 61 64 69 6e 67 20 69 73 20 6f 66 66 20 62 79 oading is off by
345e0 20 64 65 66 61 75 6c 74 2e 20 53 65 65 20 74 69 default. See ti
345f0 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 20 5e cket #1863..** ^
34600 43 61 6c 6c 20 74 68 65 20 73 71 6c 69 74 65 33 Call the sqlite3
34610 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 _enable_load_ext
34620 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65 ension() routine
34630 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a with onoff==1.*
34640 2a 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 * to turn extens
34650 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 ion loading on a
34660 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20 nd call it with
34670 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e onoff==0 to turn
34680 0a 2a 2a 20 69 74 20 62 61 63 6b 20 6f 66 66 20 .** it back off
34690 61 67 61 69 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 again..*/.SQLITE
346a0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
346b0 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 _enable_load_ext
346c0 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a ension(sqlite3 *
346d0 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a db, int onoff);.
346e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
346f0 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c Automatically L
34700 6f 61 64 20 53 74 61 74 69 63 61 6c 6c 79 20 4c oad Statically L
34710 69 6e 6b 65 64 20 45 78 74 65 6e 73 69 6f 6e 73 inked Extensions
34720 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 .**.** ^This int
34730 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68 erface causes th
34740 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 e xEntryPoint()
34750 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 function to be i
34760 6e 76 6f 6b 65 64 20 66 6f 72 0a 2a 2a 20 65 61 nvoked for.** ea
34770 63 68 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 ch new [database
34780 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 connection] tha
34790 74 20 69 73 20 63 72 65 61 74 65 64 2e 20 20 54 t is created. T
347a0 68 65 20 69 64 65 61 20 68 65 72 65 20 69 73 20 he idea here is
347b0 74 68 61 74 0a 2a 2a 20 78 45 6e 74 72 79 50 6f that.** xEntryPo
347c0 69 6e 74 28 29 20 69 73 20 74 68 65 20 65 6e 74 int() is the ent
347d0 72 79 20 70 6f 69 6e 74 20 66 6f 72 20 61 20 73 ry point for a s
347e0 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 tatically linked
347f0 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f SQLite extensio
34800 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 74 6f 20 n.** that is to
34810 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 be automatically
34820 20 6c 6f 61 64 65 64 20 69 6e 74 6f 20 61 6c 6c loaded into all
34830 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f new database co
34840 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a nnections..**.**
34850 20 5e 28 45 76 65 6e 20 74 68 6f 75 67 68 20 74 ^(Even though t
34860 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 72 6f 74 he function prot
34870 6f 74 79 70 65 20 73 68 6f 77 73 20 74 68 61 74 otype shows that
34880 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 74 xEntryPoint() t
34890 61 6b 65 73 0a 2a 2a 20 6e 6f 20 61 72 67 75 6d akes.** no argum
348a0 65 6e 74 73 20 61 6e 64 20 72 65 74 75 72 6e 73 ents and returns
348b0 20 76 6f 69 64 2c 20 53 51 4c 69 74 65 20 69 6e void, SQLite in
348c0 76 6f 6b 65 73 20 78 45 6e 74 72 79 50 6f 69 6e vokes xEntryPoin
348d0 74 28 29 20 77 69 74 68 20 74 68 72 65 65 0a 2a t() with three.*
348e0 2a 20 61 72 67 75 6d 65 6e 74 73 20 61 6e 64 20 * arguments and
348f0 65 78 70 65 63 74 73 20 61 6e 64 20 69 6e 74 65 expects and inte
34900 67 65 72 20 72 65 73 75 6c 74 20 61 73 20 69 66 ger result as if
34910 20 74 68 65 20 73 69 67 6e 61 74 75 72 65 20 6f the signature o
34920 66 20 74 68 65 0a 2a 2a 20 65 6e 74 72 79 20 70 f the.** entry p
34930 6f 69 6e 74 20 77 68 65 72 65 20 61 73 20 66 6f oint where as fo
34940 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c llows:.**.** <bl
34950 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
34960 2a 20 26 6e 62 73 70 3b 20 20 69 6e 74 20 78 45 * int xE
34970 6e 74 72 79 50 6f 69 6e 74 28 0a 2a 2a 20 26 6e ntryPoint(.** &n
34980 62 73 70 3b 20 20 20 20 73 71 6c 69 74 65 33 20 bsp; sqlite3
34990 2a 64 62 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 *db,.**
349a0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 const char **p
349b0 7a 45 72 72 4d 73 67 2c 0a 2a 2a 20 26 6e 62 73 zErrMsg,.** &nbs
349c0 70 3b 20 20 20 20 63 6f 6e 73 74 20 73 74 72 75 p; const stru
349d0 63 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 ct sqlite3_api_r
349e0 6f 75 74 69 6e 65 73 20 2a 70 54 68 75 6e 6b 0a outines *pThunk.
349f0 2a 2a 20 26 6e 62 73 70 3b 20 20 29 3b 0a 2a 2a ** );.**
34a00 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 </pre></blockqu
34a10 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49 66 20 ote>)^.**.** If
34a20 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 20 the xEntryPoint
34a30 72 6f 75 74 69 6e 65 20 65 6e 63 6f 75 6e 74 65 routine encounte
34a40 72 73 20 61 6e 20 65 72 72 6f 72 2c 20 69 74 20 rs an error, it
34a50 73 68 6f 75 6c 64 20 6d 61 6b 65 20 2a 70 7a 45 should make *pzE
34a60 72 72 4d 73 67 0a 2a 2a 20 70 6f 69 6e 74 20 74 rrMsg.** point t
34a70 6f 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 o an appropriate
34a80 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 28 error message (
34a90 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 obtained from [s
34aa0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 qlite3_mprintf()
34ab0 5d 29 0a 2a 2a 20 61 6e 64 20 72 65 74 75 72 6e ]).** and return
34ac0 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 an appropriate
34ad0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 20 20 5e [error code]. ^
34ae0 53 51 4c 69 74 65 20 65 6e 73 75 72 65 73 20 74 SQLite ensures t
34af0 68 61 74 20 2a 70 7a 45 72 72 4d 73 67 0a 2a 2a hat *pzErrMsg.**
34b00 20 69 73 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 is NULL before
34b10 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 45 6e 74 calling the xEnt
34b20 72 79 50 6f 69 6e 74 28 29 2e 20 20 5e 53 51 4c ryPoint(). ^SQL
34b30 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a ite will invoke.
34b40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ** [sqlite3_free
34b50 28 29 5d 20 6f 6e 20 2a 70 7a 45 72 72 4d 73 67 ()] on *pzErrMsg
34b60 20 61 66 74 65 72 20 78 45 6e 74 72 79 50 6f 69 after xEntryPoi
34b70 6e 74 28 29 20 72 65 74 75 72 6e 73 2e 20 20 5e nt() returns. ^
34b80 49 66 20 61 6e 79 0a 2a 2a 20 78 45 6e 74 72 79 If any.** xEntry
34b90 50 6f 69 6e 74 28 29 20 72 65 74 75 72 6e 73 20 Point() returns
34ba0 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 20 5b 73 an error, the [s
34bb0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 qlite3_open()],
34bc0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 [sqlite3_open16(
34bd0 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 )],.** or [sqlit
34be0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 63 61 e3_open_v2()] ca
34bf0 6c 6c 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 ll that provoked
34c00 20 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 the xEntryPoint
34c10 28 29 20 77 69 6c 6c 20 66 61 69 6c 2e 0a 2a 2a () will fail..**
34c20 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c .** ^Calling sql
34c30 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 ite3_auto_extens
34c40 69 6f 6e 28 58 29 20 77 69 74 68 20 61 6e 20 65 ion(X) with an e
34c50 6e 74 72 79 20 70 6f 69 6e 74 20 58 20 74 68 61 ntry point X tha
34c60 74 20 69 73 20 61 6c 72 65 61 64 79 0a 2a 2a 20 t is already.**
34c70 6f 6e 20 74 68 65 20 6c 69 73 74 20 6f 66 20 61 on the list of a
34c80 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 utomatic extensi
34c90 6f 6e 73 20 69 73 20 61 20 68 61 72 6d 6c 65 73 ons is a harmles
34ca0 73 20 6e 6f 2d 6f 70 2e 20 5e 4e 6f 20 65 6e 74 s no-op. ^No ent
34cb0 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 77 69 6c 6c ry point.** will
34cc0 20 62 65 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 be called more
34cd0 74 68 61 6e 20 6f 6e 63 65 20 66 6f 72 20 65 61 than once for ea
34ce0 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ch database conn
34cf0 65 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6f ection that is o
34d00 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 pened..**.** See
34d10 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
34d20 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e reset_auto_exten
34d30 73 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 sion()]..*/.SQLI
34d40 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
34d50 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f e3_auto_extensio
34d60 6e 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50 n(void (*xEntryP
34d70 6f 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f oint)(void));../
34d80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
34d90 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45 eset Automatic E
34da0 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 xtension Loading
34db0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 .**.** ^This int
34dc0 65 72 66 61 63 65 20 64 69 73 61 62 6c 65 73 20 erface disables
34dd0 61 6c 6c 20 61 75 74 6f 6d 61 74 69 63 20 65 78 all automatic ex
34de0 74 65 6e 73 69 6f 6e 73 20 70 72 65 76 69 6f 75 tensions previou
34df0 73 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 sly.** registere
34e00 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 d using [sqlite3
34e10 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 _auto_extension(
34e20 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 )]..*/.SQLITE_AP
34e30 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 I void sqlite3_r
34e40 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 eset_auto_extens
34e50 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a ion(void);../*.*
34e60 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 * The interface
34e70 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 to the virtual-t
34e80 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69 able mechanism i
34e90 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 s currently cons
34ea0 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 idered.** to be
34eb0 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 experimental. T
34ec0 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 he interface mig
34ed0 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 ht change in inc
34ee0 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a ompatible ways..
34ef0 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20 ** If this is a
34f00 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c problem for you,
34f10 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 do not use the
34f20 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69 interface at thi
34f30 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 s time..**.** Wh
34f40 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 en the virtual-t
34f50 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 able mechanism s
34f60 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 tabilizes, we wi
34f70 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a ll declare the.*
34f80 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 * interface fixe
34f90 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e d, support it in
34fa0 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 definitely, and
34fb0 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d remove this comm
34fc0 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 ent..*/../*.** S
34fd0 74 72 75 63 74 75 72 65 73 20 75 73 65 64 20 62 tructures used b
34fe0 79 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 y the virtual ta
34ff0 62 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f ble interface.*/
35000 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
35010 73 71 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c sqlite3_vtab sql
35020 69 74 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 ite3_vtab;.typed
35030 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
35040 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 3_index_info sql
35050 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b ite3_index_info;
35060 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
35070 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 sqlite3_vtab_cur
35080 73 6f 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62 sor sqlite3_vtab
35090 5f 63 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 _cursor;.typedef
350a0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
350b0 6d 6f 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d module sqlite3_m
350c0 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 odule;../*.** CA
350d0 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 PI3REF: Virtual
350e0 54 61 62 6c 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 Table Object.**
350f0 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 KEYWORDS: sqlite
35100 33 5f 6d 6f 64 75 6c 65 20 7b 76 69 72 74 75 61 3_module {virtua
35110 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 7d 0a l table module}.
35120 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63 **.** This struc
35130 74 75 72 65 2c 20 73 6f 6d 65 74 69 6d 65 73 20 ture, sometimes
35140 63 61 6c 6c 65 64 20 61 20 22 76 69 72 74 75 61 called a "virtua
35150 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 22 2c l table module",
35160 20 0a 2a 2a 20 64 65 66 69 6e 65 73 20 74 68 65 .** defines the
35170 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
35180 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 of a [virtual ta
35190 62 6c 65 73 5d 2e 20 20 0a 2a 2a 20 54 68 69 73 bles]. .** This
351a0 20 73 74 72 75 63 74 75 72 65 20 63 6f 6e 73 69 structure consi
351b0 73 74 73 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 sts mostly of me
351c0 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f thods for the mo
351d0 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 76 dule..**.** ^A v
351e0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 irtual table mod
351f0 75 6c 65 20 69 73 20 63 72 65 61 74 65 64 20 62 ule is created b
35200 79 20 66 69 6c 6c 69 6e 67 20 69 6e 20 61 20 70 y filling in a p
35210 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 69 6e 73 ersistent.** ins
35220 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 tance of this st
35230 72 75 63 74 75 72 65 20 61 6e 64 20 70 61 73 73 ructure and pass
35240 69 6e 67 20 61 20 70 6f 69 6e 74 65 72 20 74 6f ing a pointer to
35250 20 74 68 61 74 20 69 6e 73 74 61 6e 63 65 0a 2a that instance.*
35260 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 * to [sqlite3_cr
35270 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6f eate_module()] o
35280 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 r [sqlite3_creat
35290 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 5d 2e 0a e_module_v2()]..
352a0 2a 2a 20 5e 54 68 65 20 72 65 67 69 73 74 72 61 ** ^The registra
352b0 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 76 61 6c tion remains val
352c0 69 64 20 75 6e 74 69 6c 20 69 74 20 69 73 20 72 id until it is r
352d0 65 70 6c 61 63 65 64 20 62 79 20 61 20 64 69 66 eplaced by a dif
352e0 66 65 72 65 6e 74 0a 2a 2a 20 6d 6f 64 75 6c 65 ferent.** module
352f0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 5b 64 or until the [d
35300 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
35310 6f 6e 5d 20 63 6c 6f 73 65 73 2e 20 20 54 68 65 on] closes. The
35320 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 6f 66 20 74 content.** of t
35330 68 69 73 20 73 74 72 75 63 74 75 72 65 20 6d 75 his structure mu
35340 73 74 20 6e 6f 74 20 63 68 61 6e 67 65 20 77 68 st not change wh
35350 69 6c 65 20 69 74 20 69 73 20 72 65 67 69 73 74 ile it is regist
35360 65 72 65 64 20 77 69 74 68 0a 2a 2a 20 61 6e 79 ered with.** any
35370 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
35380 74 69 6f 6e 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 tion..*/.struct
35390 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b sqlite3_module {
353a0 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b . int iVersion;
353b0 0a 20 20 69 6e 74 20 28 2a 78 43 72 65 61 74 65 . int (*xCreate
353c0 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 )(sqlite3*, void
353d0 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 *pAux,.
353e0 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c int argc,
353f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e const char *con
35400 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 st*argv,.
35410 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f sqlite3_
35420 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 vtab **ppVTab, c
35430 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a har**);. int (*
35440 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 xConnect)(sqlite
35450 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 3*, void *pAux,.
35460 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 i
35470 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 nt argc, const c
35480 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c har *const*argv,
35490 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 .
354a0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 sqlite3_vtab **p
354b0 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a pVTab, char**);.
354c0 20 20 69 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 int (*xBestInd
354d0 65 78 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 ex)(sqlite3_vtab
354e0 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 *pVTab, sqlite3
354f0 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 _index_info*);.
35500 20 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65 int (*xDisconne
35510 63 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 ct)(sqlite3_vtab
35520 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 *pVTab);. int
35530 28 2a 78 44 65 73 74 72 6f 79 29 28 73 71 6c 69 (*xDestroy)(sqli
35540 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 te3_vtab *pVTab)
35550 3b 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 ;. int (*xOpen)
35560 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 (sqlite3_vtab *p
35570 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 VTab, sqlite3_vt
35580 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 ab_cursor **ppCu
35590 72 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 rsor);. int (*x
355a0 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 Close)(sqlite3_v
355b0 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 tab_cursor*);.
355c0 69 6e 74 20 28 2a 78 46 69 6c 74 65 72 29 28 73 int (*xFilter)(s
355d0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 qlite3_vtab_curs
355e0 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c or*, int idxNum,
355f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 69 64 78 const char *idx
35600 53 74 72 2c 0a 20 20 20 20 20 20 20 20 20 20 20 Str,.
35610 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 73 int argc, s
35620 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61 qlite3_value **a
35630 72 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e rgv);. int (*xN
35640 65 78 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 ext)(sqlite3_vta
35650 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e b_cursor*);. in
35660 74 20 28 2a 78 45 6f 66 29 28 73 71 6c 69 74 65 t (*xEof)(sqlite
35670 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 3_vtab_cursor*);
35680 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e . int (*xColumn
35690 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 )(sqlite3_vtab_c
356a0 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f ursor*, sqlite3_
356b0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a context*, int);.
356c0 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 64 29 28 int (*xRowid)(
356d0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 sqlite3_vtab_cur
356e0 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e sor*, sqlite3_in
356f0 74 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20 t64 *pRowid);.
35700 69 6e 74 20 28 2a 78 55 70 64 61 74 65 29 28 73 int (*xUpdate)(s
35710 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c 20 69 qlite3_vtab *, i
35720 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 nt, sqlite3_valu
35730 65 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e e **, sqlite3_in
35740 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a t64 *);. int (*
35750 78 42 65 67 69 6e 29 28 73 71 6c 69 74 65 33 5f xBegin)(sqlite3_
35760 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 vtab *pVTab);.
35770 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c int (*xSync)(sql
35780 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 ite3_vtab *pVTab
35790 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d );. int (*xComm
357a0 69 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 it)(sqlite3_vtab
357b0 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 *pVTab);. int
357c0 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c (*xRollback)(sql
357d0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 ite3_vtab *pVTab
357e0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e 64 );. int (*xFind
357f0 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74 65 Function)(sqlite
35800 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69 3_vtab *pVtab, i
35810 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63 nt nArg, const c
35820 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 har *zName,.
35830 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
35840 20 20 20 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e void (**pxFun
35850 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 c)(sqlite3_conte
35860 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f xt*,int,sqlite3_
35870 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20 value**),.
35880 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
35890 20 76 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a void **ppArg);.
358a0 20 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 int (*xRename)
358b0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 (sqlite3_vtab *p
358c0 56 74 61 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 Vtab, const char
358d0 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a *zNew);.};../*.
358e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 ** CAPI3REF: Vir
358f0 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 tual Table Index
35900 69 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 0a ing Information.
35910 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c ** KEYWORDS: sql
35920 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a ite3_index_info.
35930 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
35940 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 3_index_info str
35950 75 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 73 ucture and its s
35960 75 62 73 74 72 75 63 74 75 72 65 73 20 69 73 20 ubstructures is
35970 75 73 65 64 20 61 73 20 70 61 72 74 0a 2a 2a 20 used as part.**
35980 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 of the [virtual
35990 74 61 62 6c 65 5d 20 69 6e 74 65 72 66 61 63 65 table] interface
359a0 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f to.** pass info
359b0 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 rmation into and
359c0 20 72 65 63 65 69 76 65 20 74 68 65 20 72 65 70 receive the rep
359d0 6c 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42 65 ly from the [xBe
359e0 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 68 stIndex].** meth
359f0 6f 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c od of a [virtual
35a00 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 table module].
35a10 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65 The fields unde
35a20 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65 r **Inputs** are
35a30 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74 the.** inputs t
35a40 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64 o xBestIndex and
35a50 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 are read-only.
35a60 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65 xBestIndex inse
35a70 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c rts its.** resul
35a80 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75 ts into the **Ou
35a90 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a tputs** fields..
35aa0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 43 6f 6e **.** ^(The aCon
35ab0 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 straint[] array
35ac0 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c records WHERE cl
35ad0 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 ause constraints
35ae0 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a of the form:.**
35af0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
35b00 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c 2f column OP expr</
35b10 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
35b20 2a 20 77 68 65 72 65 20 4f 50 20 69 73 20 3d 2c * where OP is =,
35b30 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67 <, <=, &g
35b40 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 29 5e 20 t;, or >=.)^
35b50 20 5e 28 54 68 65 20 70 61 72 74 69 63 75 6c 61 ^(The particula
35b60 72 20 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a r operator is.**
35b70 20 73 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73 stored in aCons
35b80 74 72 61 69 6e 74 5b 5d 2e 6f 70 20 75 73 69 6e traint[].op usin
35b90 67 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 g one of the.**
35ba0 5b 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f [SQLITE_INDEX_CO
35bb0 4e 53 54 52 41 49 4e 54 5f 45 51 20 7c 20 53 51 NSTRAINT_EQ | SQ
35bc0 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 LITE_INDEX_CONST
35bd0 52 41 49 4e 54 5f 20 76 61 6c 75 65 73 5d 2e 29 RAINT_ values].)
35be0 5e 0a 2a 2a 20 5e 28 54 68 65 20 69 6e 64 65 78 ^.** ^(The index
35bf0 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 of the column i
35c00 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 61 s stored in.** a
35c10 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f Constraint[].iCo
35c20 6c 75 6d 6e 2e 29 5e 20 20 5e 28 61 43 6f 6e 73 lumn.)^ ^(aCons
35c30 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 traint[].usable
35c40 69 73 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a is TRUE if the.*
35c50 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69 * expr on the ri
35c60 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61 ght-hand side ca
35c70 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 28 n be evaluated (
35c80 61 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e and thus the con
35c90 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 straint.** is us
35ca0 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20 able) and false
35cb0 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 29 5e 0a if it cannot.)^.
35cc0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 70 74 69 6d **.** ^The optim
35cd0 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c izer automatical
35ce0 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73 ly inverts terms
35cf0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78 of the form "ex
35d00 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a pr OP column".**
35d10 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 and makes other
35d20 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 simplifications
35d30 20 74 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c to the WHERE cl
35d40 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d ause in an attem
35d50 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 pt to.** get as
35d60 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73 many WHERE claus
35d70 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 e terms into the
35d80 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 form shown abov
35d90 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a e as possible..*
35da0 2a 20 5e 54 68 65 20 61 43 6f 6e 73 74 72 61 69 * ^The aConstrai
35db0 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20 nt[] array only
35dc0 72 65 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c reports WHERE cl
35dd0 61 75 73 65 20 74 65 72 6d 73 20 74 68 61 74 20 ause terms that
35de0 61 72 65 0a 2a 2a 20 72 65 6c 65 76 61 6e 74 20 are.** relevant
35df0 74 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 to the particula
35e00 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 r virtual table
35e10 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a being queried..*
35e20 2a 0a 2a 2a 20 5e 49 6e 66 6f 72 6d 61 74 69 6f *.** ^Informatio
35e30 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45 n about the ORDE
35e40 52 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 73 R BY clause is s
35e50 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42 tored in aOrderB
35e60 79 5b 5d 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 65 y[]..** ^Each te
35e70 72 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72 rm of aOrderBy r
35e80 65 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 ecords a column
35e90 6f 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 of the ORDER BY
35ea0 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 clause..**.** Th
35eb0 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 20 6d e [xBestIndex] m
35ec0 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 ethod must fill
35ed0 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 aConstraintUsage
35ee0 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 [] with informat
35ef0 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 ion.** about wha
35f00 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 t parameters to
35f10 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65 72 2e pass to xFilter.
35f20 20 20 5e 49 66 20 61 72 67 76 49 6e 64 65 78 3e ^If argvIndex>
35f30 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69 0 then.** the ri
35f40 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 ght-hand side of
35f50 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 the correspondi
35f60 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d ng aConstraint[]
35f70 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a is evaluated.**
35f80 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 68 65 and becomes the
35f90 20 61 72 67 76 49 6e 64 65 78 2d 74 68 20 65 6e argvIndex-th en
35fa0 74 72 79 20 69 6e 20 61 72 67 76 2e 20 20 5e 28 try in argv. ^(
35fb0 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 If aConstraintUs
35fc0 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 age[].omit.** is
35fd0 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20 true, then the
35fe0 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61 73 constraint is as
35ff0 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c 6c sumed to be full
36000 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68 65 y handled by the
36010 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c .** virtual tabl
36020 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 65 e and is not che
36030 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53 51 cked again by SQ
36040 4c 69 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 Lite.)^.**.** ^T
36050 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 he idxNum and id
36060 78 50 74 72 20 76 61 6c 75 65 73 20 61 72 65 20 xPtr values are
36070 72 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73 recorded and pas
36080 73 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 sed into the.**
36090 5b 78 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64 [xFilter] method
360a0 2e 0a 2a 2a 20 5e 5b 73 71 6c 69 74 65 33 5f 66 ..** ^[sqlite3_f
360b0 72 65 65 28 29 5d 20 69 73 20 75 73 65 64 20 74 ree()] is used t
360c0 6f 20 66 72 65 65 20 69 64 78 50 74 72 20 69 66 o free idxPtr if
360d0 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 and only if.**
360e0 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50 74 72 needToFreeIdxPtr
360f0 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 is true..**.**
36100 5e 54 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 ^The orderByCons
36110 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20 umed means that
36120 6f 75 74 70 75 74 20 66 72 6f 6d 20 5b 78 46 69 output from [xFi
36130 6c 74 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69 lter]/[xNext] wi
36140 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 ll occur in.** t
36150 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72 he correct order
36160 20 74 6f 20 73 61 74 69 73 66 79 20 74 68 65 20 to satisfy the
36170 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 ORDER BY clause
36180 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72 so that no separ
36190 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 ate.** sorting s
361a0 74 65 70 20 69 73 20 72 65 71 75 69 72 65 64 2e tep is required.
361b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 73 74 69 .**.** ^The esti
361c0 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20 matedCost value
361d0 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f is an estimate o
361e0 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f f the cost of do
361f0 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 ing the.** parti
36200 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 cular lookup. A
36210 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 full scan of a
36220 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 table with N ent
36230 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 ries should have
36240 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e .** a cost of N.
36250 20 20 41 20 62 69 6e 61 72 79 20 73 65 61 72 63 A binary searc
36260 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20 h of a table of
36270 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 N entries should
36280 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 have a.** cost
36290 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 of approximately
362a0 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 log(N)..*/.stru
362b0 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 ct sqlite3_index
362c0 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 _info {. /* Inp
362d0 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f uts */. int nCo
362e0 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 nstraint;
362f0 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 /* Number of
36300 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e entries in aCon
36310 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 straint */. str
36320 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 uct sqlite3_inde
36330 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 x_constraint {.
36340 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b int iColumn;
36350 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
36360 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d Column on left-
36370 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e hand side of con
36380 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 straint */.
36390 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 unsigned char op
363a0 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e ; /* Con
363b0 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 straint operator
363c0 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 */. unsigne
363d0 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 d char usable;
363e0 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 /* True if th
363f0 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 is constraint is
36400 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 usable */.
36410 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b int iTermOffset;
36420 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 /* Use
36430 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 d internally - x
36440 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 BestIndex should
36450 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a ignore */. } *
36460 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 aConstraint;
36470 20 20 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 /* Table
36480 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 of WHERE clause
36490 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a constraints */.
364a0 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 int nOrderBy;
364b0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
364c0 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 Number of terms
364d0 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 in the ORDER BY
364e0 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 clause */. stru
364f0 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 ct sqlite3_index
36500 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20 _orderby {.
36510 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 int iColumn;
36520 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c /* Col
36530 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 umn number */.
36540 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 unsigned char
36550 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 desc; /*
36560 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20 True for DESC.
36570 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a False for ASC. *
36580 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b /. } *aOrderBy;
36590 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
365a0 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59 20 63 * The ORDER BY c
365b0 6c 61 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 lause */. /* Ou
365c0 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 tputs */. struc
365d0 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f t sqlite3_index_
365e0 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65 constraint_usage
365f0 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49 {. int argvI
36600 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20 20 20 ndex;
36610 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 /* if >0, constr
36620 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20 aint is part of
36630 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20 argv to xFilter
36640 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20 */. unsigned
36650 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 char omit;
36660 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 /* Do not code a
36670 20 74 65 73 74 20 66 6f 72 20 74 68 69 73 20 63 test for this c
36680 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d onstraint */. }
36690 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 *aConstraintUsa
366a0 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d ge;. int idxNum
366b0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ;
366c0 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20 /* Number used
366d0 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 to identify the
366e0 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 index */. char
366f0 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20 20 20 *idxStr;
36700 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c /* String,
36710 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e possibly obtain
36720 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ed from sqlite3_
36730 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 malloc */. int
36740 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53 74 72 needToFreeIdxStr
36750 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69 ; /* Free i
36760 64 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69 dxStr using sqli
36770 74 65 33 5f 66 72 65 65 28 29 20 69 66 20 74 72 te3_free() if tr
36780 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 ue */. int orde
36790 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 rByConsumed;
367a0 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 /* True if ou
367b0 74 70 75 74 20 69 73 20 61 6c 72 65 61 64 79 20 tput is already
367c0 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 ordered */. dou
367d0 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 ble estimatedCos
367e0 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d t; /* Estim
367f0 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69 ated cost of usi
36800 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f ng this index */
36810 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .};../*.** CAPI3
36820 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 REF: Virtual Tab
36830 6c 65 20 43 6f 6e 73 74 72 61 69 6e 74 20 4f 70 le Constraint Op
36840 65 72 61 74 6f 72 20 43 6f 64 65 73 0a 2a 2a 0a erator Codes.**.
36850 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73 20 ** These macros
36860 64 65 66 69 6e 65 64 20 74 68 65 20 61 6c 6c 6f defined the allo
36870 77 65 64 20 76 61 6c 75 65 73 20 66 6f 72 20 74 wed values for t
36880 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 he.** [sqlite3_i
36890 6e 64 65 78 5f 69 6e 66 6f 5d 2e 61 43 6f 6e 73 ndex_info].aCons
368a0 74 72 61 69 6e 74 5b 5d 2e 6f 70 20 66 69 65 6c traint[].op fiel
368b0 64 2e 20 20 45 61 63 68 20 76 61 6c 75 65 20 72 d. Each value r
368c0 65 70 72 65 73 65 6e 74 73 0a 2a 2a 20 61 6e 20 epresents.** an
368d0 6f 70 65 72 61 74 6f 72 20 74 68 61 74 20 69 73 operator that is
368e0 20 70 61 72 74 20 6f 66 20 61 20 63 6f 6e 73 74 part of a const
368f0 72 61 69 6e 74 20 74 65 72 6d 20 69 6e 20 74 68 raint term in th
36900 65 20 77 48 45 52 45 20 63 6c 61 75 73 65 20 6f e wHERE clause o
36910 66 0a 2a 2a 20 61 20 71 75 65 72 79 20 74 68 61 f.** a query tha
36920 74 20 75 73 65 73 20 61 20 5b 76 69 72 74 75 61 t uses a [virtua
36930 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 23 64 65 l table]..*/.#de
36940 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 fine SQLITE_INDE
36950 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 X_CONSTRAINT_EQ
36960 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 2.#define SQL
36970 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 ITE_INDEX_CONSTR
36980 41 49 4e 54 5f 47 54 20 20 20 20 34 0a 23 64 65 AINT_GT 4.#de
36990 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 fine SQLITE_INDE
369a0 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20 X_CONSTRAINT_LE
369b0 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 8.#define SQL
369c0 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 ITE_INDEX_CONSTR
369d0 41 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23 64 AINT_LT 16.#d
369e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 efine SQLITE_IND
369f0 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45 EX_CONSTRAINT_GE
36a00 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53 32.#define S
36a10 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 QLITE_INDEX_CONS
36a20 54 52 41 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a TRAINT_MATCH 64.
36a30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
36a40 20 52 65 67 69 73 74 65 72 20 41 20 56 69 72 74 Register A Virt
36a50 75 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d ual Table Implem
36a60 65 6e 74 61 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e entation.**.** ^
36a70 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
36a80 72 65 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 re used to regis
36a90 74 65 72 20 61 20 6e 65 77 20 5b 76 69 72 74 75 ter a new [virtu
36aa0 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d al table module]
36ab0 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 4d 6f 64 75 6c name..** ^Modul
36ac0 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20 e names must be
36ad0 72 65 67 69 73 74 65 72 65 64 20 62 65 66 6f 72 registered befor
36ae0 65 0a 2a 2a 20 63 72 65 61 74 69 6e 67 20 61 20 e.** creating a
36af0 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61 62 new [virtual tab
36b00 6c 65 5d 20 75 73 69 6e 67 20 74 68 65 20 6d 6f le] using the mo
36b10 64 75 6c 65 20 61 6e 64 20 62 65 66 6f 72 65 20 dule and before
36b20 75 73 69 6e 67 20 61 0a 2a 2a 20 70 72 65 65 78 using a.** preex
36b30 69 73 74 69 6e 67 20 5b 76 69 72 74 75 61 6c 20 isting [virtual
36b40 74 61 62 6c 65 5d 20 66 6f 72 20 74 68 65 20 6d table] for the m
36b50 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 odule..**.** ^Th
36b60 65 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 69 73 e module name is
36b70 20 72 65 67 69 73 74 65 72 65 64 20 6f 6e 20 74 registered on t
36b80 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
36b90 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 nection] specifi
36ba0 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 ed.** by the fir
36bb0 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e st parameter. ^
36bc0 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 The name of the
36bd0 6d 6f 64 75 6c 65 20 69 73 20 67 69 76 65 6e 20 module is given
36be0 62 79 20 74 68 65 20 0a 2a 2a 20 73 65 63 6f 6e by the .** secon
36bf0 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 d parameter. ^T
36c00 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
36c10 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 er is a pointer
36c20 74 6f 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d to.** the implem
36c30 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 entation of the
36c40 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d [virtual table m
36c50 6f 64 75 6c 65 5d 2e 20 20 20 5e 54 68 65 20 66 odule]. ^The f
36c60 6f 75 72 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 ourth.** paramet
36c70 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 er is an arbitra
36c80 72 79 20 63 6c 69 65 6e 74 20 64 61 74 61 20 70 ry client data p
36c90 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 ointer that is p
36ca0 61 73 73 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a assed through.**
36cb0 20 69 6e 74 6f 20 74 68 65 20 5b 78 43 72 65 61 into the [xCrea
36cc0 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 te] and [xConnec
36cd0 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 74 68 t] methods of th
36ce0 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 e virtual table
36cf0 6d 6f 64 75 6c 65 0a 2a 2a 20 77 68 65 6e 20 61 module.** when a
36d00 20 6e 65 77 20 76 69 72 74 75 61 6c 20 74 61 62 new virtual tab
36d10 6c 65 20 69 73 20 62 65 20 62 65 69 6e 67 20 63 le is be being c
36d20 72 65 61 74 65 64 20 6f 72 20 72 65 69 6e 69 74 reated or reinit
36d30 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e ialized..**.** ^
36d40 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 The sqlite3_crea
36d50 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 20 69 te_module_v2() i
36d60 6e 74 65 72 66 61 63 65 20 68 61 73 20 61 20 66 nterface has a f
36d70 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 77 ifth parameter w
36d80 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 hich.** is a poi
36d90 6e 74 65 72 20 74 6f 20 61 20 64 65 73 74 72 75 nter to a destru
36da0 63 74 6f 72 20 66 6f 72 20 74 68 65 20 70 43 6c ctor for the pCl
36db0 69 65 6e 74 44 61 74 61 2e 20 20 5e 53 51 4c 69 ientData. ^SQLi
36dc0 74 65 20 77 69 6c 6c 0a 2a 2a 20 69 6e 76 6f 6b te will.** invok
36dd0 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 e the destructor
36de0 20 66 75 6e 63 74 69 6f 6e 20 28 69 66 20 69 74 function (if it
36df0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 77 68 is not NULL) wh
36e00 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 6e 6f 20 en SQLite.** no
36e10 6c 6f 6e 67 65 72 20 6e 65 65 64 73 20 74 68 65 longer needs the
36e20 20 70 43 6c 69 65 6e 74 44 61 74 61 20 70 6f 69 pClientData poi
36e30 6e 74 65 72 2e 20 20 5e 54 68 65 20 64 65 73 74 nter. ^The dest
36e40 72 75 63 74 6f 72 20 77 69 6c 6c 20 61 6c 73 6f ructor will also
36e50 0a 2a 2a 20 62 65 20 69 6e 76 6f 6b 65 64 20 69 .** be invoked i
36e60 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 f the call to sq
36e70 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 lite3_create_mod
36e80 75 6c 65 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a ule_v2() fails..
36e90 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
36ea0 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 0a create_module().
36eb0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 ** interface is
36ec0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 71 equivalent to sq
36ed0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 lite3_create_mod
36ee0 75 6c 65 5f 76 32 28 29 20 77 69 74 68 20 61 20 ule_v2() with a
36ef0 4e 55 4c 4c 0a 2a 2a 20 64 65 73 74 72 75 63 74 NULL.** destruct
36f00 6f 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 or..*/.SQLITE_AP
36f10 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 I int sqlite3_cr
36f20 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 eate_module(. s
36f30 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
36f40 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c /* SQL
36f50 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 ite connection t
36f60 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c o register modul
36f70 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 e with */. cons
36f80 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 t char *zName,
36f90 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f /* Name o
36fa0 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a f the module */.
36fb0 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f const sqlite3_
36fc0 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 module *p, /*
36fd0 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 Methods for the
36fe0 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 module */. void
36ff0 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 20 20 20 *pClientData
37000 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 /* Client
37010 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 data for xCreat
37020 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b e/xConnect */.);
37030 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
37040 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d sqlite3_create_m
37050 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73 71 6c 69 odule_v2(. sqli
37060 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
37070 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 /* SQLite
37080 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 connection to r
37090 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 egister module w
370a0 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 ith */. const c
370b0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 har *zName,
370c0 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 /* Name of t
370d0 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 he module */. c
370e0 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 onst sqlite3_mod
370f0 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 ule *p, /* Met
37100 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 hods for the mod
37110 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 ule */. void *p
37120 43 6c 69 65 6e 74 44 61 74 61 2c 20 20 20 20 20 ClientData,
37130 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 /* Client da
37140 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 ta for xCreate/x
37150 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20 76 6f 69 Connect */. voi
37160 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 d(*xDestroy)(voi
37170 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f 64 75 6c d*) /* Modul
37180 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e e destructor fun
37190 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a ction */.);../*.
371a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 ** CAPI3REF: Vir
371b0 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 73 74 61 tual Table Insta
371c0 6e 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 nce Object.** KE
371d0 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f YWORDS: sqlite3_
371e0 76 74 61 62 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 vtab.**.** Every
371f0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 [virtual table
37200 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e module] implemen
37210 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 tation uses a su
37220 62 63 6c 61 73 73 0a 2a 2a 20 6f 66 20 74 68 69 bclass.** of thi
37230 73 20 6f 62 6a 65 63 74 20 74 6f 20 64 65 73 63 s object to desc
37240 72 69 62 65 20 61 20 70 61 72 74 69 63 75 6c 61 ribe a particula
37250 72 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 6f 66 r instance.** of
37260 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 the [virtual ta
37270 62 6c 65 5d 2e 20 20 45 61 63 68 20 73 75 62 63 ble]. Each subc
37280 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 lass will.** be
37290 74 61 69 6c 6f 72 65 64 20 74 6f 20 74 68 65 20 tailored to the
372a0 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f specific needs o
372b0 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 6d 70 f the module imp
372c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 20 lementation..**
372d0 54 68 65 20 70 75 72 70 6f 73 65 20 6f 66 20 74 The purpose of t
372e0 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 69 his superclass i
372f0 73 20 74 6f 20 64 65 66 69 6e 65 20 63 65 72 74 s to define cert
37300 61 69 6e 20 66 69 65 6c 64 73 20 74 68 61 74 20 ain fields that
37310 61 72 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20 74 6f are.** common to
37320 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c all module impl
37330 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a ementations..**.
37340 2a 2a 20 5e 56 69 72 74 75 61 6c 20 74 61 62 6c ** ^Virtual tabl
37350 65 73 20 6d 65 74 68 6f 64 73 20 63 61 6e 20 73 es methods can s
37360 65 74 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 et an error mess
37370 61 67 65 20 62 79 20 61 73 73 69 67 6e 69 6e 67 age by assigning
37380 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74 a.** string obt
37390 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 ained from [sqli
373a0 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 74 te3_mprintf()] t
373b0 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54 68 65 20 o zErrMsg. The
373c0 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a method should.**
373d0 20 74 61 6b 65 20 63 61 72 65 20 74 68 61 74 20 take care that
373e0 61 6e 79 20 70 72 69 6f 72 20 73 74 72 69 6e 67 any prior string
373f0 20 69 73 20 66 72 65 65 64 20 62 79 20 61 20 63 is freed by a c
37400 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
37410 66 72 65 65 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 free()].** prior
37420 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 61 20 to assigning a
37430 6e 65 77 20 73 74 72 69 6e 67 20 74 6f 20 7a 45 new string to zE
37440 72 72 4d 73 67 2e 20 20 5e 41 66 74 65 72 20 74 rrMsg. ^After t
37450 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 he error message
37460 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 65 64 .** is delivered
37470 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69 65 6e up to the clien
37480 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 t application, t
37490 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 he string will b
374a0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a e automatically.
374b0 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71 6c 69 ** freed by sqli
374c0 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64 20 74 te3_free() and t
374d0 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 he zErrMsg field
374e0 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e will be zeroed.
374f0 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 .*/.struct sqlit
37500 65 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73 e3_vtab {. cons
37510 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 t sqlite3_module
37520 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 *pModule; /* T
37530 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68 he module for th
37540 69 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 is virtual table
37550 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20 */. int nRef;
37560 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
37570 20 20 20 20 20 20 2f 2a 20 4e 4f 20 4c 4f 4e 47 /* NO LONG
37580 45 52 20 55 53 45 44 20 2a 2f 0a 20 20 63 68 61 ER USED */. cha
37590 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20 20 r *zErrMsg;
375a0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
375b0 45 72 72 6f 72 20 6d 65 73 73 61 67 65 20 66 72 Error message fr
375c0 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e om sqlite3_mprin
375d0 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 tf() */. /* Vir
375e0 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 tual table imple
375f0 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 mentations will
37600 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 typically add ad
37610 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 ditional fields
37620 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.};../*.** CAP
37630 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 I3REF: Virtual T
37640 61 62 6c 65 20 43 75 72 73 6f 72 20 4f 62 6a 65 able Cursor Obje
37650 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 ct.** KEYWORDS:
37660 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 sqlite3_vtab_cur
37670 73 6f 72 20 7b 76 69 72 74 75 61 6c 20 74 61 62 sor {virtual tab
37680 6c 65 20 63 75 72 73 6f 72 7d 0a 2a 2a 0a 2a 2a le cursor}.**.**
37690 20 45 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20 Every [virtual
376a0 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d table module] im
376b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 plementation use
376c0 73 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 s a subclass of
376d0 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 the.** following
376e0 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 64 65 structure to de
376f0 73 63 72 69 62 65 20 63 75 72 73 6f 72 73 20 74 scribe cursors t
37700 68 61 74 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74 hat point into t
37710 68 65 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 he.** [virtual t
37720 61 62 6c 65 5d 20 61 6e 64 20 61 72 65 20 75 73 able] and are us
37730 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74 68 ed.** to loop th
37740 72 6f 75 67 68 20 74 68 65 20 76 69 72 74 75 61 rough the virtua
37750 6c 20 74 61 62 6c 65 2e 20 20 43 75 72 73 6f 72 l table. Cursor
37760 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 s are created us
37770 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 ing the.** [sqli
37780 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 4f 70 65 6e te3_module.xOpen
37790 20 7c 20 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 | xOpen] method
377a0 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 61 of the module a
377b0 6e 64 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 nd are destroyed
377c0 0a 2a 2a 20 62 79 20 74 68 65 20 5b 73 71 6c 69 .** by the [sqli
377d0 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 43 6c 6f 73 te3_module.xClos
377e0 65 20 7c 20 78 43 6c 6f 73 65 5d 20 6d 65 74 68 e | xClose] meth
377f0 6f 64 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65 od. Cursors are
37800 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 used.** by the
37810 5b 78 46 69 6c 74 65 72 5d 2c 20 5b 78 4e 65 78 [xFilter], [xNex
37820 74 5d 2c 20 5b 78 45 6f 66 5d 2c 20 5b 78 43 6f t], [xEof], [xCo
37830 6c 75 6d 6e 5d 2c 20 61 6e 64 20 5b 78 52 6f 77 lumn], and [xRow
37840 69 64 5d 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f id] methods.** o
37850 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 f the module. E
37860 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 ach module imple
37870 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 64 mentation will d
37880 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f 6e efine.** the con
37890 74 65 6e 74 20 6f 66 20 61 20 63 75 72 73 6f 72 tent of a cursor
378a0 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 73 75 structure to su
378b0 69 74 20 69 74 73 20 6f 77 6e 20 6e 65 65 64 73 it its own needs
378c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75 70 ..**.** This sup
378d0 65 72 63 6c 61 73 73 20 65 78 69 73 74 73 20 69 erclass exists i
378e0 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 66 69 6e n order to defin
378f0 65 20 66 69 65 6c 64 73 20 6f 66 20 74 68 65 20 e fields of the
37900 63 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20 61 cursor that.** a
37910 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c re common to all
37920 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
37930 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 ..*/.struct sqli
37940 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 te3_vtab_cursor
37950 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 {. sqlite3_vtab
37960 20 2a 70 56 74 61 62 3b 20 20 20 20 20 20 2f 2a *pVtab; /*
37970 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6f Virtual table o
37980 66 20 74 68 69 73 20 63 75 72 73 6f 72 20 2a 2f f this cursor */
37990 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 . /* Virtual ta
379a0 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ble implementati
379b0 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c ons will typical
379c0 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 ly add additiona
379d0 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a l fields */.};..
379e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
379f0 44 65 63 6c 61 72 65 20 54 68 65 20 53 63 68 65 Declare The Sche
37a00 6d 61 20 4f 66 20 41 20 56 69 72 74 75 61 6c 20 ma Of A Virtual
37a10 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 Table.**.** ^The
37a20 20 5b 78 43 72 65 61 74 65 5d 20 61 6e 64 20 5b [xCreate] and [
37a30 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64 xConnect] method
37a40 73 20 6f 66 20 61 0a 2a 2a 20 5b 76 69 72 74 75 s of a.** [virtu
37a50 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d al table module]
37a60 20 63 61 6c 6c 20 74 68 69 73 20 69 6e 74 65 72 call this inter
37a70 66 61 63 65 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 face.** to decla
37a80 72 65 20 74 68 65 20 66 6f 72 6d 61 74 20 28 74 re the format (t
37a90 68 65 20 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 he names and dat
37aa0 61 74 79 70 65 73 20 6f 66 20 74 68 65 20 63 6f atypes of the co
37ab0 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65 lumns) of.** the
37ac0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 virtual tables
37ad0 74 68 65 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a they implement..
37ae0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
37af0 74 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 t sqlite3_declar
37b00 65 5f 76 74 61 62 28 73 71 6c 69 74 65 33 2a 2c e_vtab(sqlite3*,
37b10 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 51 const char *zSQ
37b20 4c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 L);../*.** CAPI3
37b30 52 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20 41 20 REF: Overload A
37b40 46 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41 20 56 Function For A V
37b50 69 72 74 75 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a irtual Table.**.
37b60 2a 2a 20 5e 28 56 69 72 74 75 61 6c 20 74 61 62 ** ^(Virtual tab
37b70 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64 65 20 les can provide
37b80 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70 6c alternative impl
37b90 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66 ementations of f
37ba0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e unctions.** usin
37bb0 67 20 74 68 65 20 5b 78 46 69 6e 64 46 75 6e 63 g the [xFindFunc
37bc0 74 69 6f 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 tion] method of
37bd0 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62 the [virtual tab
37be0 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 0a 2a 2a le module]. .**
37bf0 20 42 75 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 But global vers
37c00 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20 66 75 ions of those fu
37c10 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 nctions.** must
37c20 65 78 69 73 74 20 69 6e 20 6f 72 64 65 72 20 74 exist in order t
37c30 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e o be overloaded.
37c40 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 )^.**.** ^(This
37c50 41 50 49 20 6d 61 6b 65 73 20 73 75 72 65 20 61 API makes sure a
37c60 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20 global version
37c70 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 of a function wi
37c80 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a th a particular.
37c90 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62 ** name and numb
37ca0 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 er of parameters
37cb0 20 65 78 69 73 74 73 2e 20 20 49 66 20 6e 6f 20 exists. If no
37cc0 73 75 63 68 20 66 75 6e 63 74 69 6f 6e 20 65 78 such function ex
37cd0 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74 ists.** before t
37ce0 68 69 73 20 41 50 49 20 69 73 20 63 61 6c 6c 65 his API is calle
37cf0 64 2c 20 61 20 6e 65 77 20 66 75 6e 63 74 69 6f d, a new functio
37d00 6e 20 69 73 20 63 72 65 61 74 65 64 2e 29 5e 20 n is created.)^
37d10 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 ^The implementa
37d20 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6e tion.** of the n
37d30 65 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c 77 61 ew function alwa
37d40 79 73 20 63 61 75 73 65 73 20 61 6e 20 65 78 63 ys causes an exc
37d50 65 70 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 72 eption to be thr
37d60 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 20 own. So.** the
37d70 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 new function is
37d80 6e 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61 6e 79 not good for any
37d90 74 68 69 6e 67 20 62 79 20 69 74 73 65 6c 66 2e thing by itself.
37da0 20 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75 Its only.** pu
37db0 72 70 6f 73 65 20 69 73 20 74 6f 20 62 65 20 61 rpose is to be a
37dc0 20 70 6c 61 63 65 68 6f 6c 64 65 72 20 66 75 6e placeholder fun
37dd0 63 74 69 6f 6e 20 74 68 61 74 20 63 61 6e 20 62 ction that can b
37de0 65 20 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 e overloaded.**
37df0 62 79 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 by a [virtual ta
37e00 62 6c 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f ble]..*/.SQLITE_
37e10 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
37e20 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f overload_functio
37e30 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 n(sqlite3*, cons
37e40 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d t char *zFuncNam
37e50 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f e, int nArg);../
37e60 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 *.** The interfa
37e70 63 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 ce to the virtua
37e80 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 l-table mechanis
37e90 6d 20 64 65 66 69 6e 65 64 20 61 62 6f 76 65 20 m defined above
37ea0 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 (back up.** to a
37eb0 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 comment remarka
37ec0 62 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 bly similar to t
37ed0 68 69 73 20 6f 6e 65 29 20 69 73 20 63 75 72 72 his one) is curr
37ee0 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 ently considered
37ef0 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 .** to be experi
37f00 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 mental. The int
37f10 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 erface might cha
37f20 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 nge in incompati
37f30 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 ble ways..** If
37f40 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 this is a proble
37f50 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f m for you, do no
37f60 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 t use the interf
37f70 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 ace at this time
37f80 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 ..**.** When the
37f90 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d virtual-table m
37fa0 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 echanism stabili
37fb0 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 zes, we will dec
37fc0 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 lare the.** inte
37fd0 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 rface fixed, sup
37fe0 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 port it indefini
37ff0 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 tely, and remove
38000 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a this comment..*
38010 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 /../*.** CAPI3RE
38020 46 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 41 F: A Handle To A
38030 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 20 4b n Open BLOB.** K
38040 45 59 57 4f 52 44 53 3a 20 7b 42 4c 4f 42 20 68 EYWORDS: {BLOB h
38050 61 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20 68 61 6e andle} {BLOB han
38060 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 dles}.**.** An i
38070 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 nstance of this
38080 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 object represent
38090 73 20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20 6f s an open BLOB o
380a0 6e 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 n which.** [sqli
380b0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 te3_blob_open |
380c0 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 incremental BLOB
380d0 20 49 2f 4f 5d 20 63 61 6e 20 62 65 20 70 65 72 I/O] can be per
380e0 66 6f 72 6d 65 64 2e 0a 2a 2a 20 5e 4f 62 6a 65 formed..** ^Obje
380f0 63 74 73 20 6f 66 20 74 68 69 73 20 74 79 70 65 cts of this type
38100 20 61 72 65 20 63 72 65 61 74 65 64 20 62 79 20 are created by
38110 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 [sqlite3_blob_op
38120 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 64 65 73 en()].** and des
38130 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 troyed by [sqlit
38140 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d e3_blob_close()]
38150 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 ..** ^The [sqlit
38160 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 e3_blob_read()]
38170 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f and [sqlite3_blo
38180 62 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72 b_write()] inter
38190 66 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 faces.** can be
381a0 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20 used to read or
381b0 77 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 write small subs
381c0 65 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 42 ections of the B
381d0 4c 4f 42 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 LOB..** ^The [sq
381e0 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 lite3_blob_bytes
381f0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 ()] interface re
38200 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f turns the size o
38210 66 20 74 68 65 20 42 4c 4f 42 20 69 6e 20 62 79 f the BLOB in by
38220 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 tes..*/.typedef
38230 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62 struct sqlite3_b
38240 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 lob sqlite3_blob
38250 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
38260 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46 F: Open A BLOB F
38270 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49 or Incremental I
38280 2f 4f 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 /O.**.** ^(This
38290 69 6e 74 65 72 66 61 63 65 73 20 6f 70 65 6e 73 interfaces opens
382a0 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 20 a [BLOB handle
382b0 7c 20 68 61 6e 64 6c 65 5d 20 74 6f 20 74 68 65 | handle] to the
382c0 20 42 4c 4f 42 20 6c 6f 63 61 74 65 64 0a 2a 2a BLOB located.**
382d0 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c 20 63 6f in row iRow, co
382e0 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 lumn zColumn, ta
382f0 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61 ble zTable in da
38300 74 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 tabase zDb;.** i
38310 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 n other words, t
38320 68 65 20 73 61 6d 65 20 42 4c 4f 42 20 74 68 61 he same BLOB tha
38330 74 20 77 6f 75 6c 64 20 62 65 20 73 65 6c 65 63 t would be selec
38340 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 ted by:.**.** <p
38350 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43 re>.** SELEC
38360 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a T zColumn FROM z
38370 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 52 45 20 Db.zTable WHERE
38380 5b 72 6f 77 69 64 5d 20 3d 20 69 52 6f 77 3b 0a [rowid] = iRow;.
38390 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a ** </pre>)^.**.*
383a0 2a 20 5e 49 66 20 74 68 65 20 66 6c 61 67 73 20 * ^If the flags
383b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e parameter is non
383c0 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 -zero, then the
383d0 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66 BLOB is opened f
383e0 6f 72 20 72 65 61 64 0a 2a 2a 20 61 6e 64 20 77 or read.** and w
383f0 72 69 74 65 20 61 63 63 65 73 73 2e 20 5e 49 66 rite access. ^If
38400 20 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 it is zero, the
38410 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 BLOB is opened
38420 66 6f 72 20 72 65 61 64 20 61 63 63 65 73 73 2e for read access.
38430 0a 2a 2a 20 5e 49 74 20 69 73 20 6e 6f 74 20 70 .** ^It is not p
38440 6f 73 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20 ossible to open
38450 61 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 a column that is
38460 20 70 61 72 74 20 6f 66 20 61 6e 20 69 6e 64 65 part of an inde
38470 78 20 6f 72 20 70 72 69 6d 61 72 79 20 0a 2a 2a x or primary .**
38480 20 6b 65 79 20 66 6f 72 20 77 72 69 74 69 6e 67 key for writing
38490 2e 20 5e 49 66 20 5b 66 6f 72 65 69 67 6e 20 6b . ^If [foreign k
384a0 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 20 ey constraints]
384b0 61 72 65 20 65 6e 61 62 6c 65 64 2c 20 69 74 20 are enabled, it
384c0 69 73 20 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 is .** not possi
384d0 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f ble to open a co
384e0 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 70 61 72 lumn that is par
384f0 74 20 6f 66 20 61 20 5b 63 68 69 6c 64 20 6b 65 t of a [child ke
38500 79 5d 20 66 6f 72 20 77 72 69 74 69 6e 67 2e 0a y] for writing..
38510 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 **.** ^Note that
38520 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 the database na
38530 6d 65 20 69 73 20 6e 6f 74 20 74 68 65 20 66 69 me is not the fi
38540 6c 65 6e 61 6d 65 20 74 68 61 74 20 63 6f 6e 74 lename that cont
38550 61 69 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74 61 ains.** the data
38560 62 61 73 65 20 62 75 74 20 72 61 74 68 65 72 20 base but rather
38570 74 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d the symbolic nam
38580 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 e of the databas
38590 65 20 74 68 61 74 0a 2a 2a 20 61 70 70 65 61 72 e that.** appear
385a0 73 20 61 66 74 65 72 20 74 68 65 20 41 53 20 6b s after the AS k
385b0 65 79 77 6f 72 64 20 77 68 65 6e 20 74 68 65 20 eyword when the
385c0 64 61 74 61 62 61 73 65 20 69 73 20 63 6f 6e 6e database is conn
385d0 65 63 74 65 64 20 75 73 69 6e 67 20 5b 41 54 54 ected using [ATT
385e0 41 43 48 5d 2e 0a 2a 2a 20 5e 46 6f 72 20 74 68 ACH]..** ^For th
385f0 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 e main database
38600 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 62 61 file, the databa
38610 73 65 20 6e 61 6d 65 20 69 73 20 22 6d 61 69 6e se name is "main
38620 22 2e 0a 2a 2a 20 5e 46 6f 72 20 54 45 4d 50 20 "..** ^For TEMP
38630 74 61 62 6c 65 73 2c 20 74 68 65 20 64 61 74 61 tables, the data
38640 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22 74 65 base name is "te
38650 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 mp"..**.** ^(On
38660 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 success, [SQLITE
38670 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 _OK] is returned
38680 20 61 6e 64 20 74 68 65 20 6e 65 77 20 5b 42 4c and the new [BL
38690 4f 42 20 68 61 6e 64 6c 65 5d 20 69 73 20 77 72 OB handle] is wr
386a0 69 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42 itten.** to *ppB
386b0 6c 6f 62 2e 20 4f 74 68 65 72 77 69 73 65 20 61 lob. Otherwise a
386c0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 n [error code] i
386d0 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 2a s returned and *
386e0 70 70 42 6c 6f 62 20 69 73 20 73 65 74 0a 2a 2a ppBlob is set.**
386f0 20 74 6f 20 62 65 20 61 20 6e 75 6c 6c 20 70 6f to be a null po
38700 69 6e 74 65 72 2e 29 5e 0a 2a 2a 20 5e 54 68 69 inter.)^.** ^Thi
38710 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 s function sets
38720 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
38730 6e 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72 20 nnection] error
38740 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 code and message
38750 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20 76 .** accessible v
38760 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 ia [sqlite3_errc
38770 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 ode()] and [sqli
38780 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e te3_errmsg()] an
38790 64 20 72 65 6c 61 74 65 64 0a 2a 2a 20 66 75 6e d related.** fun
387a0 63 74 69 6f 6e 73 2e 20 5e 4e 6f 74 65 20 74 68 ctions. ^Note th
387b0 61 74 20 74 68 65 20 2a 70 70 42 6c 6f 62 20 76 at the *ppBlob v
387c0 61 72 69 61 62 6c 65 20 69 73 20 61 6c 77 61 79 ariable is alway
387d0 73 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 69 6e s initialized in
387e0 20 61 0a 2a 2a 20 77 61 79 20 74 68 61 74 20 6d a.** way that m
387f0 61 6b 65 73 20 69 74 20 73 61 66 65 20 74 6f 20 akes it safe to
38800 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f invoke [sqlite3_
38810 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 20 6f 6e blob_close()] on
38820 20 2a 70 70 42 6c 6f 62 0a 2a 2a 20 72 65 67 61 *ppBlob.** rega
38830 72 64 6c 65 73 73 20