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 20 7b 48 31 30 30 31 30 7d 20 3c 53 36 30 rs {H10010} <S60
0af0: 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 100>.**.** The S
0b00: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 61 6e QLITE_VERSION an
0b10: 64 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e d SQLITE_VERSION
0b20: 5f 4e 55 4d 42 45 52 20 23 64 65 66 69 6e 65 73 _NUMBER #defines
0b30: 20 69 6e 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 in.** the sqlit
0b40: 65 33 2e 68 20 66 69 6c 65 20 73 70 65 63 69 66 e3.h file specif
0b50: 79 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6f 66 y the version of
0b60: 20 53 51 4c 69 74 65 20 77 69 74 68 20 77 68 69 SQLite with whi
0b70: 63 68 0a 2a 2a 20 74 68 61 74 20 68 65 61 64 65 ch.** that heade
0b80: 72 20 66 69 6c 65 20 69 73 20 61 73 73 6f 63 69 r file is associ
0b90: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ated..**.** The
0ba0: 22 76 65 72 73 69 6f 6e 22 20 6f 66 20 53 51 4c "version" of SQL
0bb0: 69 74 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 ite is a string
0bc0: 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 57 2e 58 of the form "W.X
0bd0: 2e 59 22 20 6f 72 20 22 57 2e 58 2e 59 2e 5a 22 .Y" or "W.X.Y.Z"
0be0: 2e 0a 2a 2a 20 54 68 65 20 57 20 76 61 6c 75 65 ..** The W value
0bf0: 20 69 73 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f is major versio
0c00: 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 69 73 20 n number and is
0c10: 61 6c 77 61 79 73 20 33 20 69 6e 20 53 51 4c 69 always 3 in SQLi
0c20: 74 65 33 2e 0a 2a 2a 20 54 68 65 20 57 20 76 61 te3..** The W va
0c30: 6c 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 lue only changes
0c40: 20 77 68 65 6e 20 62 61 63 6b 77 61 72 64 73 20 when backwards
0c50: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 69 73 compatibility is
0c60: 0a 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e 64 20 77 .** broken and w
0c70: 65 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65 76 65 e intend to neve
0c80: 72 20 62 72 65 61 6b 20 62 61 63 6b 77 61 72 64 r break backward
0c90: 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e s compatibility.
0ca0: 0a 2a 2a 20 54 68 65 20 58 20 76 61 6c 75 65 20 .** The X value
0cb0: 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 is the minor ver
0cc0: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 sion number and
0cd0: 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77 68 65 only changes whe
0ce0: 6e 0a 2a 2a 20 74 68 65 72 65 20 61 72 65 20 6d n.** there are m
0cf0: 61 6a 6f 72 20 66 65 61 74 75 72 65 20 65 6e 68 ajor feature enh
0d00: 61 6e 63 65 6d 65 6e 74 73 20 74 68 61 74 20 61 ancements that a
0d10: 72 65 20 66 6f 72 77 61 72 64 73 20 63 6f 6d 70 re forwards comp
0d20: 61 74 69 62 6c 65 0a 2a 2a 20 62 75 74 20 6e 6f atible.** but no
0d30: 74 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 t backwards comp
0d40: 61 74 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 20 59 atible..** The Y
0d50: 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 72 65 value is the re
0d60: 6c 65 61 73 65 20 6e 75 6d 62 65 72 20 61 6e 64 lease number and
0d70: 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 is incremented
0d80: 77 69 74 68 0a 2a 2a 20 65 61 63 68 20 72 65 6c with.** each rel
0d90: 65 61 73 65 20 62 75 74 20 72 65 73 65 74 73 20 ease but resets
0da0: 62 61 63 6b 20 74 6f 20 30 20 77 68 65 6e 65 76 back to 0 whenev
0db0: 65 72 20 58 20 69 73 20 69 6e 63 72 65 6d 65 6e er X is incremen
0dc0: 74 65 64 2e 0a 2a 2a 20 54 68 65 20 5a 20 76 61 ted..** The Z va
0dd0: 6c 75 65 20 6f 6e 6c 79 20 61 70 70 65 61 72 73 lue only appears
0de0: 20 6f 6e 20 62 72 61 6e 63 68 20 72 65 6c 65 61 on branch relea
0df0: 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 ses..**.** The S
0e00: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 QLITE_VERSION_NU
0e10: 4d 42 45 52 20 69 73 20 61 6e 20 69 6e 74 65 67 MBER is an integ
0e20: 65 72 20 74 68 61 74 20 69 73 20 63 6f 6d 70 75 er that is compu
0e30: 74 65 64 20 61 73 0a 2a 2a 20 66 6f 6c 6c 6f 77 ted as.** follow
0e40: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 s:.**.** <blockq
0e50: 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 53 51 uote><pre>.** SQ
0e60: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d LITE_VERSION_NUM
0e70: 42 45 52 20 3d 20 57 2a 31 30 30 30 30 30 30 20 BER = W*1000000
0e80: 2b 20 58 2a 31 30 30 30 20 2b 20 59 0a 2a 2a 20 + X*1000 + Y.**
0e90: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
0ea0: 74 65 3e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 te>.**.** Since
0eb0: 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 version 3.6.18,
0ec0: 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f SQLite source co
0ed0: 64 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f 72 de has been stor
0ee0: 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 ed in the.** <a
0ef0: 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77 href="http://www
0f00: 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f .fossil-scm.org/
0f10: 22 3e 66 6f 73 73 69 6c 20 63 6f 6e 66 69 67 75 ">fossil configu
0f20: 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e ration managemen
0f30: 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e 2e t.** system</a>.
0f40: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 The SQLITE_SOU
0f50: 52 43 45 5f 49 44 0a 2a 2a 20 6d 61 63 72 6f 20 RCE_ID.** macro
0f60: 69 73 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 is a string whic
0f70: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70 h identifies a p
0f80: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d articular check-
0f90: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 in of SQLite.**
0fa0: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 within its confi
0fb0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d guration managem
0fc0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 54 68 65 ent system. The
0fd0: 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 73 string contains
0fe0: 20 74 68 65 0a 2a 2a 20 64 61 74 65 20 61 6e 64 the.** date and
0ff0: 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65 time of the che
1000: 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20 ck-in (UTC) and
1010: 61 6e 20 53 48 41 31 20 68 61 73 68 20 6f 66 20 an SHA1 hash of
1020: 74 68 65 20 65 6e 74 69 72 65 0a 2a 2a 20 73 6f the entire.** so
1030: 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a urce tree..**.**
1040: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
1050: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 te3_libversion()
1060: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c ],.** [sqlite3_l
1070: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 ibversion_number
1080: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f ()], [sqlite3_so
1090: 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73 urceid()],.** [s
10a0: 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d qlite_version()]
10b0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 and [sqlite_sou
10c0: 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2a 0a 2a 2a rce_id()]..**.**
10d0: 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b Requirements: [
10e0: 48 31 30 30 31 31 5d 20 5b 48 31 30 30 31 34 5d H10011] [H10014]
10f0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
1100: 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20 TE_VERSION
1110: 20 20 22 33 2e 36 2e 31 38 22 0a 23 64 65 66 69 "3.6.18".#defi
1120: 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f ne SQLITE_VERSIO
1130: 4e 5f 4e 55 4d 42 45 52 20 33 30 30 36 30 31 38 N_NUMBER 3006018
1140: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1150: 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 SOURCE_ID "
1160: 32 30 30 39 2d 30 39 2d 31 31 20 31 34 3a 30 35 2009-09-11 14:05
1170: 3a 30 37 20 62 30 38 34 38 32 38 61 37 37 31 65 :07 b084828a771e
1180: 63 34 30 62 65 38 35 66 30 37 63 35 39 30 63 61 c40be85f07c590ca
1190: 39 39 64 65 34 66 36 63 32 34 65 65 22 0a 0a 2f 99de4f6c24ee"../
11a0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
11b0: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 un-Time Library
11c0: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 20 Version Numbers
11d0: 7b 48 31 30 30 32 30 7d 20 3c 53 36 30 31 30 30 {H10020} <S60100
11e0: 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 >.** KEYWORDS: s
11f0: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 0a 2a qlite3_version.*
1200: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 *.** These inter
1210: 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 faces provide th
1220: 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 e same informati
1230: 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 on as the [SQLIT
1240: 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b E_VERSION],.** [
1250: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e SQLITE_VERSION_N
1260: 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c UMBER], and [SQL
1270: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 23 ITE_SOURCE_ID] #
1280: 64 65 66 69 6e 65 73 20 69 6e 20 74 68 65 20 68 defines in the h
1290: 65 61 64 65 72 2c 0a 2a 2a 20 62 75 74 20 61 72 eader,.** but ar
12a0: 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 e associated wit
12b0: 68 20 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e h the library in
12c0: 73 74 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 stead of the hea
12d0: 64 65 72 20 66 69 6c 65 2e 20 20 43 61 75 74 69 der file. Cauti
12e0: 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 ous.** programme
12f0: 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 rs might include
1300: 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d assert() statem
1310: 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 ents in their ap
1320: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 plication to.**
1330: 76 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 verify that valu
1340: 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 es returned by t
1350: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 hese interfaces
1360: 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 match the macros
1370: 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 in.** the heade
1380: 72 2c 20 61 6e 64 20 74 68 75 73 20 69 6e 73 75 r, and thus insu
1390: 72 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c re that the appl
13a0: 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f ication is.** co
13b0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 mpiled with matc
13c0: 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 hing library and
13d0: 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a header files..*
13e0: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
13f0: 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 ><pre>.** assert
1400: 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 ( sqlite3_libver
1410: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 sion_number()==S
1420: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 QLITE_VERSION_NU
1430: 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 MBER );.** asser
1440: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 t( strcmp(sqlite
1450: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c 3_sourceid(),SQL
1460: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d ITE_SOURCE_ID)==
1470: 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 0 );.** assert(
1480: 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c strcmp(sqlite3_l
1490: 69 62 76 65 72 73 69 6f 6e 2c 53 51 4c 49 54 45 ibversion,SQLITE
14a0: 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a _VERSION)==0 );.
14b0: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
14c0: 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 quote>.**.** The
14d0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 sqlite3_libvers
14e0: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 ion() function r
14f0: 65 74 75 72 6e 73 20 74 68 65 20 73 61 6d 65 20 eturns the same
1500: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 information as i
1510: 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 71 6c 69 s.** in the sqli
1520: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 te3_version[] st
1530: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 ring constant.
1540: 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 The function is
1550: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 provided.** for
1560: 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 use in DLLs sinc
1570: 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61 e DLL users usua
1580: 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 lly do not have
1590: 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74 6f direct access to
15a0: 20 73 74 72 69 6e 67 0a 2a 2a 20 63 6f 6e 73 74 string.** const
15b0: 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65 20 ants within the
15c0: 44 4c 4c 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c DLL. Similarly,
15d0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 the sqlite3_sou
15e0: 72 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e rceid() function
15f0: 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 .** returns the
1600: 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e same information
1610: 20 61 73 20 69 73 20 69 6e 20 74 68 65 20 5b 53 as is in the [S
1620: 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d QLITE_SOURCE_ID]
1630: 20 23 64 65 66 69 6e 65 20 6f 66 0a 2a 2a 20 74 #define of.** t
1640: 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e 0a he header file..
1650: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
1660: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 [sqlite_version(
1670: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 )] and [sqlite_s
1680: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2a 0a ource_id()]..**.
1690: 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
16a0: 20 5b 48 31 30 30 32 31 5d 20 5b 48 31 30 30 32 [H10021] [H1002
16b0: 32 5d 20 5b 48 31 30 30 32 33 5d 0a 2a 2f 0a 53 2] [H10023].*/.S
16c0: 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
16d0: 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 _EXTERN const ch
16e0: 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 ar sqlite3_versi
16f0: 6f 6e 5b 5d 3b 0a 53 51 4c 49 54 45 5f 41 50 49 on[];.SQLITE_API
1700: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c const char *sql
1710: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 ite3_libversion(
1720: 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 void);.SQLITE_AP
1730: 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 I const char *sq
1740: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 76 lite3_sourceid(v
1750: 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 oid);.SQLITE_API
1760: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 int sqlite3_lib
1770: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 version_number(v
1780: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 oid);../*.** CAP
1790: 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 I3REF: Test To S
17a0: 65 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 ee If The Librar
17b0: 79 20 49 73 20 54 68 72 65 61 64 73 61 66 65 20 y Is Threadsafe
17c0: 7b 48 31 30 31 30 30 7d 20 3c 53 36 30 31 30 30 {H10100} <S60100
17d0: 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 >.**.** SQLite c
17e0: 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 an be compiled w
17f0: 69 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d ith or without m
1800: 75 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a utexes. When.**
1810: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
1820: 45 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 EADSAFE] C prepr
1830: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 ocessor macro is
1840: 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 1 or 2, mutexes
1850: 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 .** are enabled
1860: 61 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 and SQLite is th
1870: 72 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 readsafe. When
1880: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 the.** [SQLITE_T
1890: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f HREADSAFE] macro
18a0: 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d is 0, .** the m
18b0: 75 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 utexes are omitt
18c0: 65 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 ed. Without the
18d0: 20 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 mutexes, it is
18e0: 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 not safe.** to u
18f0: 73 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 se SQLite concur
1900: 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 rently from more
1910: 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 than one thread
1920: 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 ..**.** Enabling
1930: 20 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 mutexes incurs
1940: 61 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 a measurable per
1950: 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 formance penalty
1960: 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 ..** So if speed
1970: 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d is of utmost im
1980: 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b portance, it mak
1990: 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 es sense to disa
19a0: 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 ble.** the mutex
19b0: 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 es. But for max
19c0: 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 imum safety, mut
19d0: 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 exes should be e
19e0: 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68 65 20 64 nabled..** The d
19f0: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 efault behavior
1a00: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74 is for mutexes t
1a10: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a o be enabled..**
1a20: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 .** This interfa
1a30: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62 ce can be used b
1a40: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e y an application
1a50: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 to make sure th
1a60: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f at the.** versio
1a70: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 n of SQLite that
1a80: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 it is linking a
1a90: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 gainst was compi
1aa0: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 led with.** the
1ab0: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 desired setting
1ac0: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 of the [SQLITE_T
1ad0: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f HREADSAFE] macro
1ae0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 ..**.** This int
1af0: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f erface only repo
1b00: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 rts on the compi
1b10: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 le-time mutex se
1b20: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 tting.** of the
1b30: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
1b40: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 FE] flag. If SQ
1b50: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
1b60: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f with.** SQLITE_
1b70: 54 48 52 45 41 44 53 41 46 45 3d 31 20 74 68 65 THREADSAFE=1 the
1b80: 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e n mutexes are en
1b90: 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 abled by default
1ba0: 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 but.** can be f
1bb0: 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c ully or partiall
1bc0: 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 y disabled using
1bd0: 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 a call to [sqli
1be0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a te3_config()].**
1bf0: 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73 20 with the verbs
1c00: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
1c10: 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 INGLETHREAD], [S
1c20: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c QLITE_CONFIG_MUL
1c30: 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 TITHREAD],.** or
1c40: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
1c50: 4d 55 54 45 58 5d 2e 20 20 54 68 65 20 72 65 74 MUTEX]. The ret
1c60: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 urn value of thi
1c70: 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 s function shows
1c80: 0a 2a 2a 20 6f 6e 6c 79 20 74 68 65 20 64 65 66 .** only the def
1c90: 61 75 6c 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d ault compile-tim
1ca0: 65 20 73 65 74 74 69 6e 67 2c 20 6e 6f 74 20 61 e setting, not a
1cb0: 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e ny run-time chan
1cc0: 67 65 73 0a 2a 2a 20 74 6f 20 74 68 61 74 20 73 ges.** to that s
1cd0: 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 53 65 etting..**.** Se
1ce0: 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 e the [threading
1cf0: 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 mode] documenta
1d00: 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f tion for additio
1d10: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e nal information.
1d20: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
1d30: 6e 74 73 3a 20 5b 48 31 30 31 30 31 5d 20 5b 48 nts: [H10101] [H
1d40: 31 30 31 30 32 5d 0a 2a 2f 0a 53 51 4c 49 54 45 10102].*/.SQLITE
1d50: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
1d60: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 _threadsafe(void
1d70: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1d80: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e EF: Database Con
1d90: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 20 7b nection Handle {
1da0: 48 31 32 30 30 30 7d 20 3c 53 34 30 32 30 30 3e H12000} <S40200>
1db0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 .** KEYWORDS: {d
1dc0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1dd0: 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f on} {database co
1de0: 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a nnections}.**.**
1df0: 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 Each open SQLit
1e00: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65 e database is re
1e10: 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 presented by a p
1e20: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 ointer to an ins
1e30: 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 tance of.** the
1e40: 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65 opaque structure
1e50: 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 named "sqlite3"
1e60: 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 . It is useful
1e70: 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 to think of an s
1e80: 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 qlite3.** pointe
1e90: 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 r as an object.
1ea0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 The [sqlite3_op
1eb0: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f en()], [sqlite3_
1ec0: 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a open16()], and.*
1ed0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f * [sqlite3_open_
1ee0: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 v2()] interfaces
1ef0: 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 are its constru
1f00: 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 ctors, and [sqli
1f10: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 te3_close()].**
1f20: 69 73 20 69 74 73 20 64 65 73 74 72 75 63 74 6f is its destructo
1f30: 72 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 r. There are ma
1f40: 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61 ny other interfa
1f50: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 ces (such as.**
1f60: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1f70: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 _v2()], [sqlite3
1f80: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
1f90: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ()], and.** [sql
1fa0: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 ite3_busy_timeou
1fb0: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 t()] to name but
1fc0: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65 three) that are
1fd0: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a methods on an.*
1fe0: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 * sqlite3 object
1ff0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
2000: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 uct sqlite3 sqli
2010: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 te3;../*.** CAPI
2020: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 3REF: 64-Bit Int
2030: 65 67 65 72 20 54 79 70 65 73 20 7b 48 31 30 32 eger Types {H102
2040: 30 30 7d 20 3c 53 31 30 31 31 30 3e 0a 2a 2a 20 00} <S10110>.**
2050: 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 KEYWORDS: sqlite
2060: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 _int64 sqlite_ui
2070: 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 nt64.**.** Becau
2080: 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 se there is no c
2090: 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 ross-platform wa
20a0: 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d y to specify 64-
20b0: 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 bit integer type
20c0: 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c s.** SQLite incl
20d0: 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f udes typedefs fo
20e0: 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 r 64-bit signed
20f0: 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 and unsigned int
2100: 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 egers..**.** The
2110: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 sqlite3_int64 a
2120: 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 nd sqlite3_uint6
2130: 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72 4 are the prefer
2140: 72 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 red type definit
2150: 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c ions..** The sql
2160: 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 ite_int64 and sq
2170: 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 lite_uint64 type
2180: 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 s are supported
2190: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a for backwards.**
21a0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f compatibility o
21b0: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 nly..**.** Requi
21c0: 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 32 30 31 rements: [H10201
21d0: 5d 20 5b 48 31 30 32 30 32 5d 0a 2a 2f 0a 23 69 ] [H10202].*/.#i
21e0: 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 fdef SQLITE_INT6
21f0: 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 4_TYPE. typedef
2200: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 SQLITE_INT64_TY
2210: 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b PE sqlite_int64;
2220: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 . typedef unsig
2230: 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 ned SQLITE_INT64
2240: 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e _TYPE sqlite_uin
2250: 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e t64;.#elif defin
2260: 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 ed(_MSC_VER) ||
2270: 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e defined(__BORLAN
2280: 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 DC__). typedef
2290: 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 __int64 sqlite_i
22a0: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 nt64;. typedef
22b0: 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 unsigned __int64
22c0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a sqlite_uint64;.
22d0: 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 #else. typedef
22e0: 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 long long int sq
22f0: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 lite_int64;. ty
2300: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c pedef unsigned l
2310: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c ong long int sql
2320: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 ite_uint64;.#end
2330: 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 if.typedef sqlit
2340: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f e_int64 sqlite3_
2350: 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 int64;.typedef s
2360: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c qlite_uint64 sql
2370: 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a ite3_uint64;../*
2380: 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 .** If compiling
2390: 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 for a processor
23a0: 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 that lacks floa
23b0: 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f ting point suppo
23c0: 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 rt,.** substitut
23d0: 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c e integer for fl
23e0: 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f oating-point..*/
23f0: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f .#ifdef SQLITE_O
2400: 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 MIT_FLOATING_POI
2410: 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 NT.# define doub
2420: 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 le sqlite3_int64
2430: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 .#endif../*.** C
2440: 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 API3REF: Closing
2450: 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e A Database Conn
2460: 65 63 74 69 6f 6e 20 7b 48 31 32 30 31 30 7d 20 ection {H12010}
2470: 3c 53 33 30 31 30 30 3e 3c 53 34 30 32 30 30 3e <S30100><S40200>
2480: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
2490: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72 ine is the destr
24a0: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 uctor for the [s
24b0: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a qlite3] object..
24c0: 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f **.** Applicatio
24d0: 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 ns should [sqlit
24e0: 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 e3_finalize | fi
24f0: 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 nalize] all [pre
2500: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 pared statements
2510: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 ].** and [sqlite
2520: 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 3_blob_close | c
2530: 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 lose] all [BLOB
2540: 68 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 handles] associa
2550: 74 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 ted with.** the
2560: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 [sqlite3] object
2570: 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 prior to attemp
2580: 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 ting to close th
2590: 65 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 65 e object..** The
25a0: 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 [sqlite3_next_s
25b0: 74 6d 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 tmt()] interface
25c0: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
25d0: 6c 6f 63 61 74 65 20 61 6c 6c 0a 2a 2a 20 5b 70 locate all.** [p
25e0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
25f0: 74 73 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 ts] associated w
2600: 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 ith a [database
2610: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 66 20 64 connection] if d
2620: 65 73 69 72 65 64 2e 0a 2a 2a 20 54 79 70 69 63 esired..** Typic
2630: 61 6c 20 63 6f 64 65 20 6d 69 67 68 74 20 6c 6f al code might lo
2640: 6f 6b 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a ok like this:.**
2650: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
2660: 3c 70 72 65 3e 0a 2a 2a 20 73 71 6c 69 74 65 33 <pre>.** sqlite3
2670: 5f 73 74 6d 74 20 2a 70 53 74 6d 74 3b 0a 2a 2a _stmt *pStmt;.**
2680: 20 77 68 69 6c 65 28 20 28 70 53 74 6d 74 20 3d while( (pStmt =
2690: 20 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 sqlite3_next_st
26a0: 6d 74 28 64 62 2c 20 30 29 29 21 3d 30 20 29 7b mt(db, 0))!=0 ){
26b0: 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 73 71 6c .** sql
26c0: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 70 53 ite3_finalize(pS
26d0: 74 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c 2f tmt);.** }.** </
26e0: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
26f0: 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 >.**.** If [sqli
2700: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20 te3_close()] is
2710: 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 20 invoked while a
2720: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f transaction is o
2730: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e pen,.** the tran
2740: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d saction is autom
2750: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 atically rolled
2760: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 back..**.** The
2770: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b C parameter to [
2780: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 sqlite3_close(C)
2790: 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 ] must be either
27a0: 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 a NULL.** point
27b0: 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 er or an [sqlite
27c0: 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 3] object pointe
27d0: 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 r obtained.** fr
27e0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e om [sqlite3_open
27f0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ()], [sqlite3_op
2800: 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b en16()], or.** [
2810: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
2820: 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 )], and not prev
2830: 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a iously closed..*
2840: 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
2850: 73 3a 0a 2a 2a 20 5b 48 31 32 30 31 31 5d 20 5b s:.** [H12011] [
2860: 48 31 32 30 31 32 5d 20 5b 48 31 32 30 31 33 5d H12012] [H12013]
2870: 20 5b 48 31 32 30 31 34 5d 20 5b 48 31 32 30 31 [H12014] [H1201
2880: 35 5d 20 5b 48 31 32 30 31 39 5d 0a 2a 2f 0a 53 5] [H12019].*/.S
2890: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
28a0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 lite3_close(sqli
28b0: 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 te3 *);../*.** T
28c0: 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 61 he type for a ca
28d0: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e llback function.
28e0: 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61 .** This is lega
28f0: 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 65 cy and deprecate
2900: 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64 d. It is includ
2910: 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 ed for historica
2920: 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 l.** compatibili
2930: 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f ty and is not do
2940: 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 cumented..*/.typ
2950: 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 edef int (*sqlit
2960: 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 e3_callback)(voi
2970: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 d*,int,char**, c
2980: 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 har**);../*.** C
2990: 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 API3REF: One-Ste
29a0: 70 20 51 75 65 72 79 20 45 78 65 63 75 74 69 6f p Query Executio
29b0: 6e 20 49 6e 74 65 72 66 61 63 65 20 7b 48 31 32 n Interface {H12
29c0: 31 30 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 100} <S10000>.**
29d0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
29e0: 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 exec() interface
29f0: 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 74 is a convenient
2a00: 20 77 61 79 20 6f 66 20 72 75 6e 6e 69 6e 67 20 way of running
2a10: 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 53 one or more.** S
2a20: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 77 69 QL statements wi
2a30: 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20 thout having to
2a40: 77 72 69 74 65 20 61 20 6c 6f 74 20 6f 66 20 43 write a lot of C
2a50: 20 63 6f 64 65 2e 20 20 54 68 65 20 55 54 46 2d code. The UTF-
2a60: 38 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 53 51 4c 8 encoded.** SQL
2a70: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 statements are
2a80: 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 passed in as the
2a90: 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
2aa0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 r to sqlite3_exe
2ab0: 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 74 61 74 c()..** The stat
2ac0: 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 ements are evalu
2ad0: 61 74 65 64 20 6f 6e 65 20 62 79 20 6f 6e 65 20 ated one by one
2ae0: 75 6e 74 69 6c 20 65 69 74 68 65 72 20 61 6e 20 until either an
2af0: 65 72 72 6f 72 20 6f 72 0a 2a 2a 20 61 6e 20 69 error or.** an i
2b00: 6e 74 65 72 72 75 70 74 20 69 73 20 65 6e 63 6f nterrupt is enco
2b10: 75 6e 74 65 72 65 64 2c 20 6f 72 20 75 6e 74 69 untered, or unti
2b20: 6c 20 74 68 65 79 20 61 72 65 20 61 6c 6c 20 64 l they are all d
2b30: 6f 6e 65 2e 20 20 54 68 65 20 33 72 64 20 70 61 one. The 3rd pa
2b40: 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 61 6e rameter.** is an
2b50: 20 6f 70 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 optional callba
2b60: 63 6b 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b ck that is invok
2b70: 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 ed once for each
2b80: 20 72 6f 77 20 6f 66 20 61 6e 79 20 71 75 65 72 row of any quer
2b90: 79 0a 2a 2a 20 72 65 73 75 6c 74 73 20 70 72 6f y.** results pro
2ba0: 64 75 63 65 64 20 62 79 20 74 68 65 20 53 51 4c duced by the SQL
2bb0: 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 54 68 statements. Th
2bc0: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 5th parameter
2bd0: 74 65 6c 6c 73 20 77 68 65 72 65 0a 2a 2a 20 74 tells where.** t
2be0: 6f 20 77 72 69 74 65 20 61 6e 79 20 65 72 72 6f o write any erro
2bf0: 72 20 6d 65 73 73 61 67 65 73 2e 0a 2a 2a 0a 2a r messages..**.*
2c00: 2a 20 54 68 65 20 65 72 72 6f 72 20 6d 65 73 73 * The error mess
2c10: 61 67 65 20 70 61 73 73 65 64 20 62 61 63 6b 20 age passed back
2c20: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 through the 5th
2c30: 70 61 72 61 6d 65 74 65 72 20 69 73 20 68 65 6c parameter is hel
2c40: 64 0a 2a 2a 20 69 6e 20 6d 65 6d 6f 72 79 20 6f d.** in memory o
2c50: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
2c60: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e lite3_malloc()].
2c70: 20 20 54 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d To avoid a mem
2c80: 6f 72 79 20 6c 65 61 6b 2c 0a 2a 2a 20 74 68 65 ory leak,.** the
2c90: 20 63 61 6c 6c 69 6e 67 20 61 70 70 6c 69 63 61 calling applica
2ca0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 63 61 6c 6c tion should call
2cb0: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
2cc0: 5d 20 6f 6e 20 61 6e 79 20 65 72 72 6f 72 0a 2a ] on any error.*
2cd0: 2a 20 6d 65 73 73 61 67 65 20 72 65 74 75 72 6e * message return
2ce0: 65 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 ed through the 5
2cf0: 74 68 20 70 61 72 61 6d 65 74 65 72 20 77 68 65 th parameter whe
2d00: 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 n it has finishe
2d10: 64 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 65 d using.** the e
2d20: 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a rror message..**
2d30: 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 .** If the SQL s
2d40: 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 tatement in the
2d50: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 2nd parameter is
2d60: 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 NULL or an empt
2d70: 79 20 73 74 72 69 6e 67 0a 2a 2a 20 6f 72 20 61 y string.** or a
2d80: 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 string containi
2d90: 6e 67 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 ng only whitespa
2da0: 63 65 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 2c ce and comments,
2db0: 20 74 68 65 6e 20 6e 6f 20 53 51 4c 0a 2a 2a 20 then no SQL.**
2dc0: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 statements are e
2dd0: 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65 valuated and the
2de0: 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 database is not
2df0: 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 changed..**.**
2e00: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 The sqlite3_exec
2e10: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 () interface is
2e20: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 74 implemented in t
2e30: 65 72 6d 73 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 erms of.** [sqli
2e40: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
2e50: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ], [sqlite3_step
2e60: 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 ()], and [sqlite
2e70: 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 3_finalize()]..*
2e80: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 * The sqlite3_ex
2e90: 65 63 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 ec() routine doe
2ea0: 73 20 6e 6f 74 68 69 6e 67 20 74 6f 20 74 68 65 s nothing to the
2eb0: 20 64 61 74 61 62 61 73 65 20 74 68 61 74 20 63 database that c
2ec0: 61 6e 6e 6f 74 20 62 65 20 64 6f 6e 65 0a 2a 2a annot be done.**
2ed0: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 by [sqlite3_pre
2ee0: 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c pare_v2()], [sql
2ef0: 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e ite3_step()], an
2f00: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c d [sqlite3_final
2f10: 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 ize()]..**.** Th
2f20: 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
2f30: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 r to [sqlite3_ex
2f40: 65 63 28 29 5d 20 6d 75 73 74 20 62 65 20 61 6e ec()] must be an
2f50: 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 0a valid and open.
2f60: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
2f70: 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 nection]..**.**
2f80: 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e The database con
2f90: 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 nection must not
2fa0: 20 62 65 20 63 6c 6f 73 65 64 20 77 68 69 6c 65 be closed while
2fb0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 .** [sqlite3_exe
2fc0: 63 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 2e c()] is running.
2fd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 .**.** The calli
2fe0: 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 ng function shou
2ff0: 6c 64 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f ld use [sqlite3_
3000: 66 72 65 65 28 29 5d 20 74 6f 20 66 72 65 65 0a free()] to free.
3010: 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 ** the memory th
3020: 61 74 20 2a 65 72 72 6d 73 67 20 69 73 20 6c 65 at *errmsg is le
3030: 66 74 20 70 6f 69 6e 74 69 6e 67 20 61 74 20 6f ft pointing at o
3040: 6e 63 65 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a nce the error.**
3050: 20 6d 65 73 73 61 67 65 20 69 73 20 6e 6f 20 6c message is no l
3060: 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a onger needed..**
3070: 0a 2a 2a 20 54 68 65 20 53 51 4c 20 73 74 61 74 .** The SQL stat
3080: 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 20 74 68 ement text in th
3090: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 e 2nd parameter
30a0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 to [sqlite3_exec
30b0: 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 72 65 6d 61 ()].** must rema
30c0: 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 77 68 69 in unchanged whi
30d0: 6c 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 le [sqlite3_exec
30e0: 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a ()] is running..
30f0: 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
3100: 74 73 3a 0a 2a 2a 20 5b 48 31 32 31 30 31 5d 20 ts:.** [H12101]
3110: 5b 48 31 32 31 30 32 5d 20 5b 48 31 32 31 30 34 [H12102] [H12104
3120: 5d 20 5b 48 31 32 31 30 35 5d 20 5b 48 31 32 31 ] [H12105] [H121
3130: 30 37 5d 20 5b 48 31 32 31 31 30 5d 20 5b 48 31 07] [H12110] [H1
3140: 32 31 31 33 5d 20 5b 48 31 32 31 31 36 5d 0a 2a 2113] [H12116].*
3150: 2a 20 5b 48 31 32 31 31 39 5d 20 5b 48 31 32 31 * [H12119] [H121
3160: 32 32 5d 20 5b 48 31 32 31 32 35 5d 20 5b 48 31 22] [H12125] [H1
3170: 32 31 33 31 5d 20 5b 48 31 32 31 33 34 5d 20 5b 2131] [H12134] [
3180: 48 31 32 31 33 37 5d 20 5b 48 31 32 31 33 38 5d H12137] [H12138]
3190: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
31a0: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 nt sqlite3_exec(
31b0: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 . sqlite3*,
31c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
31d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
31e0: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 An open databas
31f0: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
3200: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 r *sql,
3210: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3220: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 /* SQL to be e
3230: 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e valuated */. in
3240: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f t (*callback)(vo
3250: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 id*,int,char**,c
3260: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c har**), /* Call
3270: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f back function */
3280: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 . void *,
3290: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
32a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
32b0: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 1st argument to
32c0: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 callback */. c
32d0: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 har **errmsg
32e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
32f0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 /* Err
3300: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 or msg written h
3310: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a ere */.);../*.**
3320: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c CAPI3REF: Resul
3330: 74 20 43 6f 64 65 73 20 7b 48 31 30 32 31 30 7d t Codes {H10210}
3340: 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 <S10700>.** KEY
3350: 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b WORDS: SQLITE_OK
3360: 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 {error code} {e
3370: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b rror codes}.** K
3380: 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 EYWORDS: {result
3390: 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 code} {result c
33a0: 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 odes}.**.** Many
33b0: 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e SQLite function
33c0: 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 s return an inte
33d0: 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 ger result code
33e0: 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f from the set sho
33f0: 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 wn.** here in or
3400: 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 73 der to indicates
3410: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c success or fail
3420: 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 ure..**.** New e
3430: 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 rror codes may b
3440: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
3450: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 e versions of SQ
3460: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 Lite..**.** See
3470: 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f also: [SQLITE_IO
3480: 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e ERR_READ | exten
3490: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
34a0: 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ].*/.#define SQL
34b0: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 ITE_OK
34c0: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66 0 /* Successf
34d0: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 ul result */./*
34e0: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 beginning-of-err
34f0: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 or-codes */.#def
3500: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 ine SQLITE_ERROR
3510: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53 1 /* S
3520: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 QL error or miss
3530: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a ing database */.
3540: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
3550: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20 NTERNAL 2
3560: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 /* Internal logi
3570: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 c error in SQLit
3580: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e */.#define SQL
3590: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20 ITE_PERM
35a0: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70 3 /* Access p
35b0: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 ermission denied
35c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
35d0: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20 TE_ABORT
35e0: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 4 /* Callback
35f0: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65 routine requeste
3600: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 d an abort */.#d
3610: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 efine SQLITE_BUS
3620: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a Y 5 /*
3630: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69 The database fi
3640: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a le is locked */.
3650: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
3660: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20 OCKED 6
3670: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68 /* A table in th
3680: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f e database is lo
3690: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 cked */.#define
36a0: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 SQLITE_NOMEM
36b0: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 7 /* A mal
36c0: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a loc() failed */.
36d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
36e0: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 EADONLY 8
36f0: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72 /* Attempt to wr
3700: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 ite a readonly d
3710: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 atabase */.#defi
3720: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 ne SQLITE_INTERR
3730: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 UPT 9 /* Op
3740: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 eration terminat
3750: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e ed by sqlite3_in
3760: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 terrupt()*/.#def
3770: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
3780: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53 10 /* S
3790: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b ome kind of disk
37a0: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 I/O error occur
37b0: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 red */.#define S
37c0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20 QLITE_CORRUPT
37d0: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61 11 /* The da
37e0: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67 tabase disk imag
37f0: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a e is malformed *
3800: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
3810: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20 _NOTFOUND 12
3820: 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 /* NOT USED. T
3830: 61 62 6c 65 20 6f 72 20 72 65 63 6f 72 64 20 6e able or record n
3840: 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 ot found */.#def
3850: 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 ine SQLITE_FULL
3860: 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49 13 /* I
3870: 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 nsertion failed
3880: 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73 65 because database
3890: 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 is full */.#def
38a0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f ine SQLITE_CANTO
38b0: 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55 PEN 14 /* U
38c0: 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 nable to open th
38d0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
38e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
38f0: 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 E_PROTOCOL 15
3900: 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 /* NOT USED.
3910: 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 Database lock pr
3920: 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a otocol error */.
3930: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 #define SQLITE_E
3940: 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 MPTY 16
3950: 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65 /* Database is e
3960: 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 mpty */.#define
3970: 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 SQLITE_SCHEMA
3980: 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 17 /* The d
3990: 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 atabase schema c
39a0: 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e hanged */.#defin
39b0: 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 e SQLITE_TOOBIG
39c0: 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 18 /* Str
39d0: 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 ing or BLOB exce
39e0: 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a eds size limit *
39f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
3a00: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 _CONSTRAINT 19
3a10: 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 /* Abort due t
3a20: 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f o constraint vio
3a30: 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e lation */.#defin
3a40: 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 e SQLITE_MISMATC
3a50: 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 H 20 /* Dat
3a60: 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 a type mismatch
3a70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
3a80: 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 E_MISUSE 21
3a90: 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 /* Library us
3aa0: 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a ed incorrectly *
3ab0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
3ac0: 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 _NOLFS 22
3ad0: 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 /* Uses OS fea
3ae0: 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 tures not suppor
3af0: 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 ted on host */.#
3b00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 define SQLITE_AU
3b10: 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f TH 23 /
3b20: 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 * Authorization
3b30: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e denied */.#defin
3b40: 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 e SQLITE_FORMAT
3b50: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 24 /* Aux
3b60: 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20 iliary database
3b70: 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a format error */.
3b80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
3b90: 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20 ANGE 25
3ba0: 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 /* 2nd parameter
3bb0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
3bc0: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f out of range */
3bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3be0: 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20 NOTADB 26
3bf0: 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 /* File opened
3c00: 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 that is not a da
3c10: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 tabase file */.#
3c20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f define SQLITE_RO
3c30: 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f W 100 /
3c40: 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 * sqlite3_step()
3c50: 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 has another row
3c60: 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e ready */.#defin
3c70: 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 e SQLITE_DONE
3c80: 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 101 /* sql
3c90: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 ite3_step() has
3ca0: 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 finished executi
3cb0: 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d ng */./* end-of-
3cc0: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a error-codes */..
3cd0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
3ce0: 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 Extended Result
3cf0: 43 6f 64 65 73 20 7b 48 31 30 32 32 30 7d 20 3c Codes {H10220} <
3d00: 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f S10700>.** KEYWO
3d10: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 65 RDS: {extended e
3d20: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74 65 rror code} {exte
3d30: 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 nded error codes
3d40: 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b }.** KEYWORDS: {
3d50: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
3d60: 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 code} {extended
3d70: 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a result codes}.**
3d80: 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 .** In its defau
3d90: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e lt configuration
3da0: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 , SQLite API rou
3db0: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 tines return one
3dc0: 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a 2a of 26 integer.*
3dd0: 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 * [SQLITE_OK | r
3de0: 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 esult codes]. H
3df0: 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e owever, experien
3e00: 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 ce has shown tha
3e10: 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 t many of.** the
3e20: 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 se result codes
3e30: 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 are too coarse-g
3e40: 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f rained. They do
3e50: 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a not provide as.
3e60: 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 ** much informat
3e70: 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 ion about proble
3e80: 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 ms as programmer
3e90: 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 s might like. I
3ea0: 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a n an effort to.*
3eb0: 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 * address this,
3ec0: 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f newer versions o
3ed0: 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f f SQLite (versio
3ee0: 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 n 3.3.8 and late
3ef0: 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 r) include.** su
3f00: 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 pport for additi
3f10: 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 onal result code
3f20: 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d s that provide m
3f30: 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 ore detailed inf
3f40: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 ormation.** abou
3f50: 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65 78 t errors. The ex
3f60: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
3f70: 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 des are enabled
3f80: 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f or disabled.** o
3f90: 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73 65 n a per database
3fa0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 connection basi
3fb0: 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b s using the.** [
3fc0: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
3fd0: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d _result_codes()]
3fe0: 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 API..**.** Some
3ff0: 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c of the availabl
4000: 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c e extended resul
4010: 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74 t codes are list
4020: 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 ed here..** One
4030: 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20 6e may expect the n
4040: 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64 65 umber of extende
4050: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 77 d result codes w
4060: 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a ill be expand.**
4070: 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f 66 over time. Sof
4080: 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73 20 tware that uses
4090: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
40a0: 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78 70 codes should exp
40b0: 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 ect.** to see ne
40c0: 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 69 w result codes i
40d0: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
40e0: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a s of SQLite..**.
40f0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b ** The SQLITE_OK
4100: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c result code wil
4110: 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e l never be exten
4120: 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c ded. It will al
4130: 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 ways.** be exact
4140: 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66 ly zero..*/.#def
4150: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
4160: 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 _READ
4170: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
4180: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 | (1<<8)).#defi
4190: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
41a0: 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 SHORT_READ
41b0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
41c0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (2<<8)).#defin
41d0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 e SQLITE_IOERR_W
41e0: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 RITE
41f0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
4200: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (3<<8)).#define
4210: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 SQLITE_IOERR_FS
4220: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 YNC
4230: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
4240: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (4<<8)).#define
4250: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 SQLITE_IOERR_DIR
4260: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 _FSYNC (
4270: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
4280: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 5<<8)).#define S
4290: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e QLITE_IOERR_TRUN
42a0: 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53 CATE (S
42b0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 QLITE_IOERR | (6
42c0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
42d0: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 LITE_IOERR_FSTAT
42e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
42f0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c LITE_IOERR | (7<
4300: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
4310: 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b ITE_IOERR_UNLOCK
4320: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
4330: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c ITE_IOERR | (8<<
4340: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4350: 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 TE_IOERR_RDLOCK
4360: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
4370: 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 TE_IOERR | (9<<8
4380: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
4390: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 E_IOERR_DELETE
43a0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
43b0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 E_IOERR | (10<<8
43c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
43d0: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 E_IOERR_BLOCKED
43e0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
43f0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 E_IOERR | (11<<8
4400: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
4410: 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 E_IOERR_NOMEM
4420: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
4430: 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 E_IOERR | (12<<8
4440: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
4450: 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 E_IOERR_ACCESS
4460: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
4470: 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 E_IOERR | (13<<8
4480: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
4490: 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 E_IOERR_CHECKRES
44a0: 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 ERVEDLOCK (SQLIT
44b0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 E_IOERR | (14<<8
44c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
44d0: 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 E_IOERR_LOCK
44e0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
44f0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 E_IOERR | (15<<8
4500: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
4510: 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 E_IOERR_CLOSE
4520: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
4530: 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 E_IOERR | (16<<8
4540: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
4550: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 E_IOERR_DIR_CLOS
4560: 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 E (SQLIT
4570: 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 E_IOERR | (17<<8
4580: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
4590: 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 E_LOCKED_SHAREDC
45a0: 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 ACHE (SQLIT
45b0: 45 5f 4c 4f 43 4b 45 44 20 7c 20 28 31 3c 3c 38 E_LOCKED | (1<<8
45c0: 29 20 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 ) )../*.** CAPI3
45d0: 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 REF: Flags For F
45e0: 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 ile Open Operati
45f0: 6f 6e 73 20 7b 48 31 30 32 33 30 7d 20 3c 48 31 ons {H10230} <H1
4600: 31 31 32 30 3e 20 3c 48 31 32 37 30 30 3e 0a 2a 1120> <H12700>.*
4610: 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 *.** These bit v
4620: 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 alues are intend
4630: 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 ed for use in th
4640: 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 e.** 3rd paramet
4650: 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 er to the [sqlit
4660: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e e3_open_v2()] in
4670: 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 terface and.** i
4680: 6e 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 n the 4th parame
4690: 74 65 72 20 74 6f 20 74 68 65 20 78 4f 70 65 6e ter to the xOpen
46a0: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a method of the.*
46b0: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 * [sqlite3_vfs]
46c0: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 object..*/.#defi
46d0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 ne SQLITE_OPEN_R
46e0: 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 EADONLY
46f0: 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 0x00000001 /* O
4700: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
4710: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 en_v2() */.#defi
4720: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 ne SQLITE_OPEN_R
4730: 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20 20 EADWRITE
4740: 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 0x00000002 /* O
4750: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
4760: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 en_v2() */.#defi
4770: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 ne SQLITE_OPEN_C
4780: 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20 20 REATE
4790: 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 0x00000004 /* O
47a0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
47b0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 en_v2() */.#defi
47c0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 ne SQLITE_OPEN_D
47d0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 ELETEONCLOSE
47e0: 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56 0x00000008 /* V
47f0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
4800: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 ne SQLITE_OPEN_E
4810: 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 XCLUSIVE
4820: 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56 0x00000010 /* V
4830: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
4840: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d ne SQLITE_OPEN_M
4850: 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 AIN_DB
4860: 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56 0x00000100 /* V
4870: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
4880: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 ne SQLITE_OPEN_T
4890: 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 EMP_DB
48a0: 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56 0x00000200 /* V
48b0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
48c0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 ne SQLITE_OPEN_T
48d0: 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 RANSIENT_DB
48e0: 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56 0x00000400 /* V
48f0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
4900: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d ne SQLITE_OPEN_M
4910: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 AIN_JOURNAL
4920: 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56 0x00000800 /* V
4930: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
4940: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 ne SQLITE_OPEN_T
4950: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 EMP_JOURNAL
4960: 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56 0x00001000 /* V
4970: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
4980: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 ne SQLITE_OPEN_S
4990: 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 UBJOURNAL
49a0: 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56 0x00002000 /* V
49b0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
49c0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d ne SQLITE_OPEN_M
49d0: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 ASTER_JOURNAL
49e0: 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56 0x00004000 /* V
49f0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
4a00: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e ne SQLITE_OPEN_N
4a10: 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 20 OMUTEX
4a20: 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 0x00008000 /* O
4a30: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
4a40: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 en_v2() */.#defi
4a50: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 ne SQLITE_OPEN_F
4a60: 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20 ULLMUTEX
4a70: 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 0x00010000 /* O
4a80: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
4a90: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 en_v2() */.#defi
4aa0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 ne SQLITE_OPEN_S
4ab0: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 HAREDCACHE
4ac0: 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 0x00020000 /* O
4ad0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
4ae0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 en_v2() */.#defi
4af0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 ne SQLITE_OPEN_P
4b00: 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20 20 RIVATECACHE
4b10: 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 0x00040000 /* O
4b20: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
4b30: 65 6e 5f 76 32 28 29 20 2a 2f 0a 0a 2f 2a 0a 2a en_v2() */../*.*
4b40: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 * CAPI3REF: Devi
4b50: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 ce Characteristi
4b60: 63 73 20 7b 48 31 30 32 34 30 7d 20 3c 48 31 31 cs {H10240} <H11
4b70: 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 120>.**.** The x
4b80: 44 65 76 69 63 65 43 61 70 61 62 69 6c 69 74 69 DeviceCapabiliti
4b90: 65 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 es method of the
4ba0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
4bb0: 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 hods].** object
4bc0: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 returns an integ
4bd0: 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 er which is a ve
4be0: 63 74 6f 72 20 6f 66 20 74 68 65 20 74 68 65 73 ctor of the thes
4bf0: 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 e.** bit values
4c00: 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 expressing I/O c
4c10: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f haracteristics o
4c20: 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 f the mass stora
4c30: 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 ge.** device tha
4c40: 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 t holds the file
4c50: 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 that the [sqlit
4c60: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a e3_io_methods].*
4c70: 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a * refers to..**.
4c80: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f ** The SQLITE_IO
4c90: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 CAP_ATOMIC prope
4ca0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 rty means that a
4cb0: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 ll writes of.**
4cc0: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f any size are ato
4cd0: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 mic. The SQLITE
4ce0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e _IOCAP_ATOMICnnn
4cf0: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 values.** mean
4d00: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 that writes of b
4d10: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e locks that are n
4d20: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 nn bytes in size
4d30: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 and.** are alig
4d40: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 ned to an addres
4d50: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e s which is an in
4d60: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f teger multiple o
4d70: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f f.** nnn are ato
4d80: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 mic. The SQLITE
4d90: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 _IOCAP_SAFE_APPE
4da0: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a ND value means.*
4db0: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 * that when data
4dc0: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 is appended to
4dd0: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 a file, the data
4de0: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 is appended.**
4df0: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 first then the s
4e00: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 ize of the file
4e10: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 is extended, nev
4e20: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 er the other.**
4e30: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 way around. The
4e40: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 SQLITE_IOCAP_SE
4e50: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 QUENTIAL propert
4e60: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 y means that.**
4e70: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 information is w
4e80: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 ritten to disk i
4e90: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 n the same order
4ea0: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 as calls.** to
4eb0: 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 xWrite()..*/.#de
4ec0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
4ed0: 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 P_ATOMIC
4ee0: 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 0x00000001.#de
4ef0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
4f00: 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 P_ATOMIC512
4f10: 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 0x00000002.#de
4f20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
4f30: 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 P_ATOMIC1K
4f40: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 0x00000004.#de
4f50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
4f60: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 P_ATOMIC2K
4f70: 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 0x00000008.#de
4f80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
4f90: 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 P_ATOMIC4K
4fa0: 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 0x00000010.#de
4fb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
4fc0: 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 P_ATOMIC8K
4fd0: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 0x00000020.#de
4fe0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
4ff0: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 P_ATOMIC16K
5000: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 0x00000040.#de
5010: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
5020: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 P_ATOMIC32K
5030: 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 0x00000080.#de
5040: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
5050: 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 P_ATOMIC64K
5060: 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 0x00000100.#de
5070: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
5080: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 P_SAFE_APPEND
5090: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 0x00000200.#de
50a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
50b0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 P_SEQUENTIAL
50c0: 20 20 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0x00000400../*
50d0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 .** CAPI3REF: Fi
50e0: 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c le Locking Level
50f0: 73 20 7b 48 31 30 32 35 30 7d 20 3c 48 31 31 31 s {H10250} <H111
5100: 32 30 3e 20 3c 48 31 31 33 31 30 3e 0a 2a 2a 0a 20> <H11310>.**.
5110: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f ** SQLite uses o
5120: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 ne of these inte
5130: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 ger values as th
5140: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 e second.** argu
5150: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 ment to calls it
5160: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c makes to the xL
5170: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 ock() and xUnloc
5180: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f k() methods.** o
5190: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f f an [sqlite3_io
51a0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 _methods] object
51b0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
51c0: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 ITE_LOCK_NONE
51d0: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 0.#define
51e0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 SQLITE_LOCK_SHA
51f0: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 RED 1.#de
5200: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b fine SQLITE_LOCK
5210: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 _RESERVED 2
5220: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5230: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 LOCK_PENDING
5240: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 3.#define SQL
5250: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 ITE_LOCK_EXCLUSI
5260: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 VE 4../*.**
5270: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 CAPI3REF: Synchr
5280: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 onization Type F
5290: 6c 61 67 73 20 7b 48 31 30 32 36 30 7d 20 3c 48 lags {H10260} <H
52a0: 31 31 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 11120>.**.** Whe
52b0: 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 n SQLite invokes
52c0: 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 the xSync() met
52d0: 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 hod of an.** [sq
52e0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
52f0: 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 ] object it uses
5300: 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f a combination o
5310: 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 f.** these integ
5320: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 er values as the
5330: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
5340: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 ..**.** When the
5350: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 SQLITE_SYNC_DAT
5360: 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 AONLY flag is us
5370: 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 ed, it means tha
5380: 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 t the.** sync op
5390: 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 eration only nee
53a0: 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 ds to flush data
53b0: 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 to mass storage
53c0: 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f . Inode.** info
53d0: 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 rmation need not
53e0: 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 be flushed. If
53f0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 the lower four b
5400: 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a its of the flag.
5410: 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f ** equal SQLITE_
5420: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 SYNC_NORMAL, tha
5430: 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e t means to use n
5440: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 ormal fsync() se
5450: 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 mantics..** If t
5460: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 he lower four bi
5470: 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f ts equal SQLITE_
5480: 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 SYNC_FULL, that
5490: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 means.** to use
54a0: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 Mac OS X style f
54b0: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 ullsync instead
54c0: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 of fsync()..*/.#
54d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 define SQLITE_SY
54e0: 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 NC_NORMAL
54f0: 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 0x00002.#define
5500: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c SQLITE_SYNC_FUL
5510: 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 L 0x000
5520: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 03.#define SQLIT
5530: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 E_SYNC_DATAONLY
5540: 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0x00010../*
5550: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 .** CAPI3REF: OS
5560: 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 Interface Open
5570: 46 69 6c 65 20 48 61 6e 64 6c 65 20 7b 48 31 31 File Handle {H11
5580: 31 31 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 110} <S20110>.**
5590: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f .** An [sqlite3_
55a0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 file] object rep
55b0: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 resents an open
55c0: 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 file in the .**
55d0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f [sqlite3_vfs | O
55e0: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 S interface laye
55f0: 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 r]. Individual
5600: 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 OS interface.**
5610: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
5620: 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 will.** want to
5630: 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 subclass this ob
5640: 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e ject by appendin
5650: 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 g additional fie
5660: 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 lds.** for their
5670: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 own use. The p
5680: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 Methods entry is
5690: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
56a0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f .** [sqlite3_io_
56b0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 methods] object
56c0: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 that defines met
56d0: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d hods for perform
56e0: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 ing.** I/O opera
56f0: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 tions on the ope
5700: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 n file..*/.typed
5710: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
5720: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 3_file sqlite3_f
5730: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 ile;.struct sqli
5740: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e te3_file {. con
5750: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 st struct sqlite
5760: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 3_io_methods *pM
5770: 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 ethods; /* Meth
5780: 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 ods for an open
5790: 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a file */.};../*.*
57a0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 * CAPI3REF: OS I
57b0: 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 nterface File Vi
57c0: 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 rtual Methods Ob
57d0: 6a 65 63 74 20 7b 48 31 31 31 32 30 7d 20 3c 53 ject {H11120} <S
57e0: 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 45 76 65 20110>.**.** Eve
57f0: 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 ry file opened b
5800: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 y the [sqlite3_v
5810: 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 fs] xOpen method
5820: 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a populates an.**
5830: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 [sqlite3_file]
5840: 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 object (or, more
5850: 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 commonly, a sub
5860: 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 class of the.**
5870: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f [sqlite3_file] o
5880: 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f bject) with a po
5890: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 inter to an inst
58a0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a ance of this obj
58b0: 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a ect..** This obj
58c0: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 ect defines the
58d0: 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 methods used to
58e0: 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 perform various
58f0: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 operations.** ag
5900: 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 ainst the open f
5910: 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 ile represented
5920: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f by the [sqlite3_
5930: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a file] object..**
5940: 0a 2a 2a 20 49 66 20 74 68 65 20 78 4f 70 65 6e .** If the xOpen
5950: 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 method sets the
5960: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d sqlite3_file.pM
5970: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a ethods element .
5980: 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c ** to a non-NULL
5990: 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 pointer, then t
59a0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 he sqlite3_io_me
59b0: 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 thods.xClose met
59c0: 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e hod.** may be in
59d0: 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 voked even if th
59e0: 65 20 78 4f 70 65 6e 20 72 65 70 6f 72 74 65 64 e xOpen reported
59f0: 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e that it failed.
5a00: 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 The.** only wa
5a10: 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 y to prevent a c
5a20: 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f all to xClose fo
5a30: 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 llowing a failed
5a40: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 66 6f 72 xOpen.** is for
5a50: 20 74 68 65 20 78 4f 70 65 6e 20 74 6f 20 73 65 the xOpen to se
5a60: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 t the sqlite3_fi
5a70: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d le.pMethods elem
5a80: 65 6e 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a ent to NULL..**.
5a90: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 ** The flags arg
5aa0: 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d ument to xSync m
5ab0: 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 ay be one of [SQ
5ac0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c LITE_SYNC_NORMAL
5ad0: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ] or.** [SQLITE_
5ae0: 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 SYNC_FULL]. The
5af0: 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 first choice is
5b00: 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e the normal fsyn
5b10: 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f c()..** The seco
5b20: 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d nd choice is a M
5b30: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 ac OS X style fu
5b40: 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 llsync. The [SQ
5b50: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e LITE_SYNC_DATAON
5b60: 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 LY].** flag may
5b70: 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e be ORed in to in
5b80: 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 dicate that only
5b90: 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 the data of the
5ba0: 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 file.** and not
5bb0: 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 its inode needs
5bc0: 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a to be synced..*
5bd0: 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 *.** The integer
5be0: 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b values to xLock
5bf0: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 () and xUnlock()
5c00: 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c are one of.** <
5c10: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c ul>.** <li> [SQL
5c20: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a ITE_LOCK_NONE],.
5c30: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
5c40: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a LOCK_SHARED],.**
5c50: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f <li> [SQLITE_LO
5c60: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a CK_RESERVED],.**
5c70: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f <li> [SQLITE_LO
5c80: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a CK_PENDING], or.
5c90: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
5ca0: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e LOCK_EXCLUSIVE].
5cb0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f .** </ul>.** xLo
5cc0: 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 ck() increases t
5cd0: 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b he lock. xUnlock
5ce0: 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65 () decreases the
5cf0: 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 lock..** The xC
5d00: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b heckReservedLock
5d10: 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 () method checks
5d20: 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 whether any dat
5d30: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
5d40: 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 ,.** either in t
5d50: 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 his process or i
5d60: 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f n some other pro
5d70: 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 cess, is holding
5d80: 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 a RESERVED,.**
5d90: 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c PENDING, or EXCL
5da0: 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 USIVE lock on th
5db0: 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 e file. It retu
5dc0: 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 rns true.** if s
5dd0: 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 uch a lock exist
5de0: 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 s and false othe
5df0: 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 rwise..**.** The
5e00: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 xFileControl()
5e10: 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 method is a gene
5e20: 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 ric interface th
5e30: 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d at allows custom
5e40: 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e .** VFS implemen
5e50: 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 tations to direc
5e60: 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f tly control an o
5e70: 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 pen file using t
5e80: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 he.** [sqlite3_f
5e90: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 ile_control()] i
5ea0: 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 nterface. The s
5eb0: 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d econd "op" argum
5ec0: 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 ent is an.** int
5ed0: 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 eger opcode. Th
5ee0: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 e third argument
5ef0: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f is a generic po
5f00: 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 inter intended t
5f10: 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 o.** point to a
5f20: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d structure that m
5f30: 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d ay contain argum
5f40: 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e ents or space in
5f50: 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 which to.** wri
5f60: 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 te return values
5f70: 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 . Potential use
5f80: 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 s for xFileContr
5f90: 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a ol() might be.**
5fa0: 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e functions to en
5fb0: 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f able blocking lo
5fc0: 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 cks with timeout
5fd0: 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 s, to change the
5fe0: 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 .** locking stra
5ff0: 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c tegy (for exampl
6000: 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c e to use dot-fil
6010: 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 e locks), to inq
6020: 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 uire.** about th
6030: 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f e status of a lo
6040: 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 ck, or to break
6050: 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 stale locks. Th
6060: 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 e SQLite.** core
6070: 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 reserves all op
6080: 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 codes less than
6090: 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 100 for its own
60a0: 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 use..** A [SQLIT
60b0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 E_FCNTL_LOCKSTAT
60c0: 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f E | list of opco
60d0: 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 des] less than 1
60e0: 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 00 is available.
60f0: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 .** Applications
6100: 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63 that define a c
6110: 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 ustom xFileContr
6120: 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 ol method should
6130: 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 use opcodes.**
6140: 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30 greater than 100
6150: 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 to avoid confli
6160: 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 cts..**.** The x
6170: 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 SectorSize() met
6180: 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 hod returns the
6190: 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 sector size of t
61a0: 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 he.** device tha
61b0: 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 t underlies the
61c0: 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f file. The secto
61d0: 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a r size is the.**
61e0: 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 minimum write t
61f0: 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f hat can be perfo
6200: 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 rmed without dis
6210: 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 turbing.** other
6220: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 bytes in the fi
6230: 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 le. The xDevice
6240: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28 Characteristics(
6250: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 ).** method retu
6260: 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 rns a bit vector
6270: 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 describing beha
6280: 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 viors of the.**
6290: 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 underlying devic
62a0: 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a e:.**.** <ul>.**
62b0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
62c0: 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c CAP_ATOMIC].** <
62d0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
62e0: 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 P_ATOMIC512].**
62f0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
6300: 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 AP_ATOMIC1K].**
6310: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
6320: 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 AP_ATOMIC2K].**
6330: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
6340: 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 AP_ATOMIC4K].**
6350: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
6360: 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 AP_ATOMIC8K].**
6370: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
6380: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a AP_ATOMIC16K].**
6390: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
63a0: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a CAP_ATOMIC32K].*
63b0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
63c0: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a OCAP_ATOMIC64K].
63d0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
63e0: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e IOCAP_SAFE_APPEN
63f0: 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 D].** <li> [SQLI
6400: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 TE_IOCAP_SEQUENT
6410: 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a IAL].** </ul>.**
6420: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 .** The SQLITE_I
6430: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 OCAP_ATOMIC prop
6440: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 erty means that
6450: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a all writes of.**
6460: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 any size are at
6470: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 omic. The SQLIT
6480: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e E_IOCAP_ATOMICnn
6490: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e n values.** mean
64a0: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 that writes of
64b0: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 blocks that are
64c0: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a nnn bytes in siz
64d0: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 e and.** are ali
64e0: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 gned to an addre
64f0: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 ss which is an i
6500: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 nteger multiple
6510: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 of.** nnn are at
6520: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 omic. The SQLIT
6530: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 E_IOCAP_SAFE_APP
6540: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a END value means.
6550: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 ** that when dat
6560: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f a is appended to
6570: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 a file, the dat
6580: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a a is appended.**
6590: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 first then the
65a0: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 size of the file
65b0: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 is extended, ne
65c0: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a ver the other.**
65d0: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 way around. Th
65e0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 e SQLITE_IOCAP_S
65f0: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 EQUENTIAL proper
6600: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a ty means that.**
6610: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 information is
6620: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 written to disk
6630: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 in the same orde
6640: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f r as calls.** to
6650: 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a xWrite()..**.**
6660: 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75 If xRead() retu
6670: 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 rns SQLITE_IOERR
6680: 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d _SHORT_READ it m
6690: 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a ust also fill.**
66a0: 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70 in the unread p
66b0: 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 ortions of the b
66c0: 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73 uffer with zeros
66d0: 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a . A VFS that.**
66e0: 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 fails to zero-f
66f0: 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 ill short reads
6700: 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f might seem to wo
6710: 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a rk. However,.**
6720: 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f failure to zero
6730: 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 -fill short read
6740: 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c s will eventuall
6750: 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 y lead to.** dat
6760: 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e abase corruption
6770: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
6780: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d uct sqlite3_io_m
6790: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 ethods sqlite3_i
67a0: 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 o_methods;.struc
67b0: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 t sqlite3_io_met
67c0: 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 hods {. int iVe
67d0: 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 rsion;. int (*x
67e0: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 Close)(sqlite3_f
67f0: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 ile*);. int (*x
6800: 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 Read)(sqlite3_fi
6810: 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 le*, void*, int
6820: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e iAmt, sqlite3_in
6830: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e t64 iOfst);. in
6840: 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 t (*xWrite)(sqli
6850: 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 te3_file*, const
6860: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 void*, int iAmt
6870: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
6880: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a iOfst);. int (*
6890: 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 xTruncate)(sqlit
68a0: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 e3_file*, sqlite
68b0: 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 3_int64 size);.
68c0: 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 int (*xSync)(sq
68d0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 lite3_file*, int
68e0: 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 flags);. int (
68f0: 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 *xFileSize)(sqli
6900: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 te3_file*, sqlit
6910: 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 e3_int64 *pSize)
6920: 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 ;. int (*xLock)
6930: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
6940: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 int);. int (*xU
6950: 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 nlock)(sqlite3_f
6960: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e ile*, int);. in
6970: 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 t (*xCheckReserv
6980: 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f edLock)(sqlite3_
6990: 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 file*, int *pRes
69a0: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 Out);. int (*xF
69b0: 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 ileControl)(sqli
69c0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f te3_file*, int o
69d0: 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a p, void *pArg);.
69e0: 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 int (*xSectorS
69f0: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ize)(sqlite3_fil
6a00: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 e*);. int (*xDe
6a10: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 viceCharacterist
6a20: 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ics)(sqlite3_fil
6a30: 65 2a 29 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 e*);. /* Additi
6a40: 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 onal methods may
6a50: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 be added in fut
6a60: 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a ure releases */.
6a70: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 };../*.** CAPI3R
6a80: 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c EF: Standard Fil
6a90: 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 e Control Opcode
6aa0: 73 20 7b 48 31 31 33 31 30 7d 20 3c 53 33 30 38 s {H11310} <S308
6ab0: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 00>.**.** These
6ac0: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 integer constant
6ad0: 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f s are opcodes fo
6ae0: 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 r the xFileContr
6af0: 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 ol method.** of
6b00: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f the [sqlite3_io_
6b10: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 methods] object
6b20: 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c and for the [sql
6b30: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
6b40: 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 l()].** interfac
6b50: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 e..**.** The [SQ
6b60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 LITE_FCNTL_LOCKS
6b70: 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 TATE] opcode is
6b80: 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 used for debuggi
6b90: 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 ng. This.** opc
6ba0: 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 ode causes the x
6bb0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 FileControl meth
6bc0: 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 od to write the
6bd0: 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 current state of
6be0: 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e .** the lock (on
6bf0: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 e of [SQLITE_LOC
6c00: 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 K_NONE], [SQLITE
6c10: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a _LOCK_SHARED],.*
6c20: 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 * [SQLITE_LOCK_R
6c30: 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 ESERVED], [SQLIT
6c40: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c E_LOCK_PENDING],
6c50: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b or [SQLITE_LOCK
6c60: 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 _EXCLUSIVE]).**
6c70: 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 into an integer
6c80: 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72 that the pArg ar
6c90: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f gument points to
6ca0: 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 . This capabilit
6cb0: 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 y.** is used dur
6cc0: 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 ing testing and
6cd0: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 only needs to be
6ce0: 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 supported when
6cf0: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 SQLITE_TEST.** i
6d00: 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 23 64 s defined..*/.#d
6d10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
6d20: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 TL_LOCKSTATE
6d30: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 1.#define SQ
6d40: 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f LITE_GET_LOCKPRO
6d50: 58 59 46 49 4c 45 20 20 20 20 20 20 32 0a 23 64 XYFILE 2.#d
6d60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 efine SQLITE_SET
6d70: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 _LOCKPROXYFILE
6d80: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 3.#define SQ
6d90: 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 LITE_LAST_ERRNO
6da0: 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 0a 2f 4../
6db0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d *.** CAPI3REF: M
6dc0: 75 74 65 78 20 48 61 6e 64 6c 65 20 7b 48 31 37 utex Handle {H17
6dd0: 31 31 30 7d 20 3c 53 32 30 31 33 30 3e 0a 2a 2a 110} <S20130>.**
6de0: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f .** The mutex mo
6df0: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 dule within SQLi
6e00: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 te defines [sqli
6e10: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 te3_mutex] to be
6e20: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 an.** abstract
6e30: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 type for a mutex
6e40: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 object. The SQ
6e50: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 Lite core never
6e60: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 looks.** at the
6e70: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 internal represe
6e80: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 ntation of an [s
6e90: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 qlite3_mutex].
6ea0: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 It only.** deals
6eb0: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 with pointers t
6ec0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d o the [sqlite3_m
6ed0: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a utex] object..**
6ee0: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 .** Mutexes are
6ef0: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 created using [s
6f00: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c qlite3_mutex_all
6f10: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 oc()]..*/.typede
6f20: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
6f30: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d _mutex sqlite3_m
6f40: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 utex;../*.** CAP
6f50: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 I3REF: OS Interf
6f60: 61 63 65 20 4f 62 6a 65 63 74 20 7b 48 31 31 31 ace Object {H111
6f70: 34 30 7d 20 3c 53 32 30 31 30 30 3e 0a 2a 2a 0a 40} <S20100>.**.
6f80: 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f ** An instance o
6f90: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 f the sqlite3_vf
6fa0: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 s object defines
6fb0: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 the interface b
6fc0: 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 etween.** the SQ
6fd0: 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 Lite core and th
6fe0: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 e underlying ope
6ff0: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 rating system.
7000: 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 The "vfs".** in
7010: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
7020: 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f object stands fo
7030: 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 r "virtual file
7040: 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 system"..**.** T
7050: 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 he value of the
7060: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 iVersion field i
7070: 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 s initially 1 bu
7080: 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 t may be larger
7090: 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 in.** future ver
70a0: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e sions of SQLite.
70b0: 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 Additional fie
70c0: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e lds may be appen
70d0: 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f ded to this.** o
70e0: 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 bject when the i
70f0: 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 Version value is
7100: 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 increased. Not
7110: 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63 e that the struc
7120: 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 ture.** of the s
7130: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 qlite3_vfs objec
7140: 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 t changes in the
7150: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 transaction bet
7160: 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 ween.** SQLite v
7170: 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 ersion 3.5.9 and
7180: 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 3.6.0 and yet t
7190: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c he iVersion fiel
71a0: 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 d was not.** mod
71b0: 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ified..**.** The
71c0: 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 szOsFile field
71d0: 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 is the size of t
71e0: 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 he subclassed [s
71f0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 qlite3_file].**
7200: 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62 structure used b
7210: 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 y this VFS. mxP
7220: 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d athname is the m
7230: 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
7240: 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 .** a pathname i
7250: 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a n this VFS..**.*
7260: 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c * Registered sql
7270: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 ite3_vfs objects
7280: 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c are kept on a l
7290: 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 inked list forme
72a0: 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 d by.** the pNex
72b0: 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 t pointer. The
72c0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 [sqlite3_vfs_reg
72d0: 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 ister()].** and
72e0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 [sqlite3_vfs_unr
72f0: 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 egister()] inter
7300: 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 faces manage thi
7310: 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 s list.** in a t
7320: 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 hread-safe way.
7330: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 The [sqlite3_vf
7340: 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 s_find()] interf
7350: 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 ace.** searches
7360: 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 the list. Neith
7370: 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 er the applicati
7380: 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 on code nor the
7390: 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 VFS.** implement
73a0: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 ation should use
73b0: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 the pNext point
73c0: 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e er..**.** The pN
73d0: 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 ext field is the
73e0: 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 only field in t
73f0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a he sqlite3_vfs.*
7400: 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 * structure that
7410: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 SQLite will eve
7420: 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 r modify. SQLit
7430: 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 e will only acce
7440: 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 ss.** or modify
7450: 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 this field while
7460: 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 holding a parti
7470: 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 cular static mut
7480: 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 ex..** The appli
7490: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 cation should ne
74a0: 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 ver modify anyth
74b0: 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 ing within the s
74c0: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 qlite3_vfs.** ob
74d0: 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 ject once the ob
74e0: 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 ject has been re
74f0: 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 gistered..**.**
7500: 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 The zName field
7510: 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f holds the name o
7520: 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 f the VFS module
7530: 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 . The name must
7540: 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 .** be unique ac
7550: 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 ross all VFS mod
7560: 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 ules..**.** SQLi
7570: 74 65 20 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 te will guarante
7580: 65 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 e that the zFile
7590: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 name parameter t
75a0: 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 o xOpen.** is ei
75b0: 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e ther a NULL poin
75c0: 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 ter or string ob
75d0: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 tained.** from x
75e0: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 2e 20 FullPathname().
75f0: 20 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 SQLite further
7600: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a guarantees that.
7610: 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 ** the string wi
7620: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 ll be valid and
7630: 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 unchanged until
7640: 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 xClose() is.** c
7650: 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f alled. Because o
7660: 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 f the previous s
7670: 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 entence,.** the
7680: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 [sqlite3_file] c
7690: 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 an safely store
76a0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
76b0: 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 .** filename if
76c0: 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 it needs to reme
76d0: 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d mber the filenam
76e0: 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f e for some reaso
76f0: 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 n..** If the zFi
7700: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 lename parameter
7710: 20 69 73 20 78 4f 70 65 6e 20 69 73 20 61 20 4e is xOpen is a N
7720: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e ULL pointer then
7730: 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 xOpen.** must i
7740: 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 nvent its own te
7750: 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 mporary name for
7760: 20 74 68 65 20 66 69 6c 65 2e 20 20 57 68 65 6e the file. When
7770: 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 ever the .** xFi
7780: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 lename parameter
7790: 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c is NULL it will
77a0: 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 also be the cas
77b0: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c e that the.** fl
77c0: 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 ags parameter wi
77d0: 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 ll include [SQLI
77e0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e TE_OPEN_DELETEON
77f0: 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 CLOSE]..**.** Th
7800: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 e flags argument
7810: 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c to xOpen() incl
7820: 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 udes all bits se
7830: 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 t in.** the flag
7840: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 s argument to [s
7850: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
7860: 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 ]. Or if [sqlit
7870: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 e3_open()].** or
7880: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
7890: 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 ()] is used, the
78a0: 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 n flags includes
78b0: 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 at least.** [SQ
78c0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
78d0: 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f ITE] | [SQLITE_O
78e0: 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a PEN_CREATE]. .**
78f0: 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e If xOpen() open
7900: 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e s a file read-on
7910: 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 ly then it sets
7920: 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a *pOutFlags to.**
7930: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 include [SQLITE
7940: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e _OPEN_READONLY].
7950: 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 Other bits in
7960: 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 *pOutFlags may b
7970: 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c e set..**.** SQL
7980: 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 ite will also ad
7990: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c d one of the fol
79a0: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 lowing flags to
79b0: 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 the xOpen().** c
79c0: 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f all, depending o
79d0: 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 n the object bei
79e0: 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a ng opened:.**.**
79f0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b <ul>.** <li> [
7a00: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e SQLITE_OPEN_MAIN
7a10: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 _DB].** <li> [S
7a20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f QLITE_OPEN_MAIN_
7a30: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e JOURNAL].** <li>
7a40: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 [SQLITE_OPEN_T
7a50: 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 EMP_DB].** <li>
7a60: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 [SQLITE_OPEN_TE
7a70: 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c MP_JOURNAL].** <
7a80: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
7a90: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a N_TRANSIENT_DB].
7aa0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
7ab0: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c _OPEN_SUBJOURNAL
7ac0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 ].** <li> [SQLI
7ad0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a TE_OPEN_MASTER_J
7ae0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e OURNAL].** </ul>
7af0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 .**.** The file
7b00: 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 I/O implementati
7b10: 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f on can use the o
7b20: 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 bject type flags
7b30: 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 to.** change th
7b40: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 e way it deals w
7b50: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 ith files. For
7b60: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c example, an appl
7b70: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 ication.** that
7b80: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 does not care ab
7b90: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 out crash recove
7ba0: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d ry or rollback m
7bb0: 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 ight make.** the
7bc0: 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e open of a journ
7bd0: 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e al file a no-op.
7be0: 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 Writes to this
7bf0: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a journal would.*
7c00: 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 * also be no-ops
7c10: 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 , and any attemp
7c20: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f t to read the jo
7c30: 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 urnal would retu
7c40: 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 rn.** SQLITE_IOE
7c50: 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c RR. Or the impl
7c60: 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 ementation might
7c70: 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 recognize that
7c80: 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 a database.** fi
7c90: 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 le will be doing
7ca0: 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 page-aligned se
7cb0: 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 ctor reads and w
7cc0: 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f rites in a rando
7cd0: 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 m.** order and s
7ce0: 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 et up its I/O su
7cf0: 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e bsystem accordin
7d00: 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 gly..**.** SQLit
7d10: 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 e might also add
7d20: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c one of the foll
7d30: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 owing flags to t
7d40: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a he xOpen method:
7d50: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
7d60: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e li> [SQLITE_OPEN
7d70: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a _DELETEONCLOSE].
7d80: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
7d90: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a OPEN_EXCLUSIVE].
7da0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 ** </ul>.**.** T
7db0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f he [SQLITE_OPEN_
7dc0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 DELETEONCLOSE] f
7dd0: 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 lag means the fi
7de0: 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 le should be.**
7df0: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 deleted when it
7e00: 69 73 20 63 6c 6f 73 65 64 2e 20 20 54 68 65 20 is closed. The
7e10: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c [SQLITE_OPEN_DEL
7e20: 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 ETEONCLOSE].** w
7e30: 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 ill be set for T
7e40: 45 4d 50 20 20 64 61 74 61 62 61 73 65 73 2c 20 EMP databases,
7e50: 6a 6f 75 72 6e 61 6c 73 20 61 6e 64 20 66 6f 72 journals and for
7e60: 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a subjournals..**
7e70: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
7e80: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 OPEN_EXCLUSIVE]
7e90: 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 flag is always u
7ea0: 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 sed in conjuncti
7eb0: 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b on.** with the [
7ec0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 SQLITE_OPEN_CREA
7ed0: 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 TE] flag, which
7ee0: 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c are both directl
7ef0: 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 y.** analogous t
7f00: 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 o the O_EXCL and
7f10: 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f O_CREAT flags o
7f20: 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e f the POSIX open
7f30: 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 ().** API. The
7f40: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c SQLITE_OPEN_EXCL
7f50: 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e USIVE flag, when
7f60: 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 paired with the
7f70: 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e .** SQLITE_OPEN
7f80: 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 _CREATE, is used
7f90: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 to indicate tha
7fa0: 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c t file should al
7fb0: 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 ways.** be creat
7fc0: 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 ed, and that it
7fd0: 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 is an error if i
7fe0: 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 t already exists
7ff0: 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f ..** It is <i>no
8000: 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e t</i> used to in
8010: 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 dicate the file
8020: 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 should be opened
8030: 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 .** for exclusi
8040: 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a ve access..**.**
8050: 20 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 At least szOsFi
8060: 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f le bytes of memo
8070: 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 ry are allocated
8080: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f by SQLite.** to
8090: 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 hold the [sqli
80a0: 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 te3_file] struct
80b0: 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68 ure passed as th
80c0: 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d e third.** argum
80d0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 ent to xOpen. T
80e0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 he xOpen method
80f0: 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f does not have to
8100: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 .** allocate the
8110: 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 structure; it s
8120: 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 hould just fill
8130: 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 it in. Note tha
8140: 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d t.** the xOpen m
8150: 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 ethod must set t
8160: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e he sqlite3_file.
8170: 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 pMethods to eith
8180: 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 er.** a valid [s
8190: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
81a0: 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 s] object or to
81b0: 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 NULL. xOpen mus
81c0: 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 t do.** this eve
81d0: 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 n if the open fa
81e0: 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 ils. SQLite exp
81f0: 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71 ects that the sq
8200: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 lite3_file.pMeth
8210: 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 ods.** element w
8220: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 ill be valid aft
8230: 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 er xOpen returns
8240: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 regardless of t
8250: 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 he success.** or
8260: 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 failure of the
8270: 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a xOpen call..**.*
8280: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 * The flags argu
8290: 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 ment to xAccess(
82a0: 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 ) may be [SQLITE
82b0: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a _ACCESS_EXISTS].
82c0: 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 ** to test for t
82d0: 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 he existence of
82e0: 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 a file, or [SQLI
82f0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 TE_ACCESS_READWR
8300: 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 ITE] to.** test
8310: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 whether a file i
8320: 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 s readable and w
8330: 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c ritable, or [SQL
8340: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d ITE_ACCESS_READ]
8350: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 .** to test whet
8360: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 her a file is at
8370: 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e least readable.
8380: 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 The file can
8390: 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 be a.** director
83a0: 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 y..**.** SQLite
83b0: 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f will always allo
83c0: 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 cate at least mx
83d0: 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 Pathname+1 bytes
83e0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 for the.** outp
83f0: 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 ut buffer xFullP
8400: 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 athname. The ex
8410: 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 act size of the
8420: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a output buffer.**
8430: 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 is also passed
8440: 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 as a parameter t
8450: 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e o both methods.
8460: 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 If the output b
8470: 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 uffer.** is not
8480: 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 large enough, [S
8490: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 QLITE_CANTOPEN]
84a0: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e should be return
84b0: 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 ed. Since this i
84c0: 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 s.** handled as
84d0: 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 a fatal error by
84e0: 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 SQLite, vfs imp
84f0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f lementations sho
8500: 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 uld endeavor.**
8510: 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 to prevent this
8520: 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 by setting mxPat
8530: 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 hname to a suffi
8540: 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 ciently large va
8550: 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 lue..**.** The x
8560: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 Randomness(), xS
8570: 6c 65 65 70 28 29 2c 20 61 6e 64 20 78 43 75 72 leep(), and xCur
8580: 72 65 6e 74 54 69 6d 65 28 29 20 69 6e 74 65 72 rentTime() inter
8590: 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 faces.** are not
85a0: 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 strictly a part
85b0: 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 of the filesyst
85c0: 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 em, but they are
85d0: 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 .** included in
85e0: 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72 the VFS structur
85f0: 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 e for completene
8600: 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 ss..** The xRand
8610: 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f omness() functio
8620: 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 n attempts to re
8630: 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 turn nBytes byte
8640: 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 s.** of good-qua
8650: 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 lity randomness
8660: 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 into zOut. The
8670: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a return value is.
8680: 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 ** the actual nu
8690: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 mber of bytes of
86a0: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 randomness obta
86b0: 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c ined..** The xSl
86c0: 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 eep() method cau
86d0: 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 ses the calling
86e0: 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 thread to sleep
86f0: 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 for at.** least
8700: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 the number of mi
8710: 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e croseconds given
8720: 2e 20 20 54 68 65 20 78 43 75 72 72 65 6e 74 54 . The xCurrentT
8730: 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 ime().** method
8740: 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e returns a Julian
8750: 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 Day Number for
8760: 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 the current date
8770: 20 61 6e 64 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2f and time..**.*/
8780: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
8790: 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 sqlite3_vfs sqli
87a0: 74 65 33 5f 76 66 73 3b 0a 73 74 72 75 63 74 20 te3_vfs;.struct
87b0: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 sqlite3_vfs {.
87c0: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 int iVersion;
87d0: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 /* Stru
87e0: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 cture version nu
87f0: 6d 62 65 72 20 2a 2f 0a 20 20 69 6e 74 20 73 7a mber */. int sz
8800: 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 OsFile;
8810: 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 /* Size of su
8820: 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 bclassed sqlite3
8830: 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d _file */. int m
8840: 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 xPathname;
8850: 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 /* Maximum f
8860: 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e ile pathname len
8870: 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 gth */. sqlite3
8880: 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 _vfs *pNext;
8890: 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 /* Next regist
88a0: 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f ered VFS */. co
88b0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b nst char *zName;
88c0: 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f /* Name o
88d0: 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 f this virtual f
88e0: 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 ile system */.
88f0: 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 void *pAppData;
8900: 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e /* Poin
8910: 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 ter to applicati
8920: 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 on-specific data
8930: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 */. int (*xOpe
8940: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c n)(sqlite3_vfs*,
8950: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
8960: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 me, sqlite3_file
8970: 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 *,.
8980: 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 int flags, int
8990: 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 *pOutFlags);.
89a0: 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 int (*xDelete)(s
89b0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
89c0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
89d0: 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 int syncDir);.
89e0: 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 int (*xAccess)(s
89f0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
8a00: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
8a10: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a int flags, int *
8a20: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 pResOut);. int
8a30: 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 (*xFullPathname)
8a40: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
8a50: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
8a60: 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 , int nOut, char
8a70: 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 *zOut);. void
8a80: 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 *(*xDlOpen)(sqli
8a90: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
8aa0: 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 char *zFilename)
8ab0: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 ;. void (*xDlEr
8ac0: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ror)(sqlite3_vfs
8ad0: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 *, int nByte, ch
8ae0: 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 ar *zErrMsg);.
8af0: 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 void (*(*xDlSym)
8b00: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f (sqlite3_vfs*,vo
8b10: 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 id*, const char
8b20: 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 *zSymbol))(void)
8b30: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c ;. void (*xDlCl
8b40: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ose)(sqlite3_vfs
8b50: 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 *, void*);. int
8b60: 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 (*xRandomness)(
8b70: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e sqlite3_vfs*, in
8b80: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a t nByte, char *z
8b90: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 Out);. int (*xS
8ba0: 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 leep)(sqlite3_vf
8bb0: 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 s*, int microsec
8bc0: 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 onds);. int (*x
8bd0: 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c CurrentTime)(sql
8be0: 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c ite3_vfs*, doubl
8bf0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 e*);. int (*xGe
8c00: 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 tLastError)(sqli
8c10: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 te3_vfs*, int, c
8c20: 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77 har *);. /* New
8c30: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 fields may be a
8c40: 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 ppended in figur
8c50: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 e versions. The
8c60: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 iVersion. ** v
8c70: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d alue will increm
8c80: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 ent whenever thi
8c90: 73 20 68 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b s happens. */.};
8ca0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
8cb0: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 : Flags for the
8cc0: 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 xAccess VFS meth
8cd0: 6f 64 20 7b 48 31 31 31 39 30 7d 20 3c 48 31 31 od {H11190} <H11
8ce0: 31 34 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 140>.**.** These
8cf0: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e integer constan
8d00: 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 ts can be used a
8d10: 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 s the third para
8d20: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 meter to.** the
8d30: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f xAccess method o
8d40: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 f an [sqlite3_vf
8d50: 73 5d 20 6f 62 6a 65 63 74 2e 20 7b 45 4e 44 7d s] object. {END}
8d60: 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 They determine
8d70: 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 .** what kind of
8d80: 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 permissions the
8d90: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 xAccess method
8da0: 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a is looking for..
8db0: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 ** With SQLITE_A
8dc0: 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 CCESS_EXISTS, th
8dd0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 e xAccess method
8de0: 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b .** simply check
8df0: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 s whether the fi
8e00: 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 le exists..** Wi
8e10: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 th SQLITE_ACCESS
8e20: 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 _READWRITE, the
8e30: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a xAccess method.*
8e40: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 * checks whether
8e50: 20 74 68 65 20 66 69 6c 65 20 69 73 20 62 6f 74 the file is bot
8e60: 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 h readable and w
8e70: 72 69 74 61 62 6c 65 2e 0a 2a 2a 20 57 69 74 68 ritable..** With
8e80: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 SQLITE_ACCESS_R
8e90: 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 EAD, the xAccess
8ea0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b method.** check
8eb0: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 s whether the fi
8ec0: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 0a le is readable..
8ed0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
8ee0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 E_ACCESS_EXISTS
8ef0: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0.#define SQL
8f00: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 ITE_ACCESS_READW
8f10: 52 49 54 45 20 31 0a 23 64 65 66 69 6e 65 20 53 RITE 1.#define S
8f20: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
8f30: 44 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 D 2../*.**
8f40: 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 CAPI3REF: Initia
8f50: 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 lize The SQLite
8f60: 4c 69 62 72 61 72 79 20 7b 48 31 30 31 33 30 7d Library {H10130}
8f70: 20 3c 53 32 30 30 30 30 3e 3c 53 33 30 31 30 30 <S20000><S30100
8f80: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 >.**.** The sqli
8f90: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
8fa0: 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c routine initial
8fb0: 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 izes the.** SQLi
8fc0: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 te library. The
8fd0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
8fe0: 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 n() routine.** d
8ff0: 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 eallocates any r
9000: 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 esources that we
9010: 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 re allocated by
9020: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
9030: 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 ze()..**.** A ca
9040: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e ll to sqlite3_in
9050: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e itialize() is an
9060: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c "effective" cal
9070: 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 l if it is.** th
9080: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c e first time sql
9090: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
90a0: 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 ) is invoked dur
90b0: 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 ing the lifetime
90c0: 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 of.** the proce
90d0: 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 ss, or if it is
90e0: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 the first time s
90f0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
9100: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a e() is invoked.*
9110: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 * following a ca
9120: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 ll to sqlite3_sh
9130: 75 74 64 6f 77 6e 28 29 2e 20 20 4f 6e 6c 79 20 utdown(). Only
9140: 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c an effective cal
9150: 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f l.** of sqlite3_
9160: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 initialize() doe
9170: 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 s any initializa
9180: 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 tion. All other
9190: 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 calls.** are ha
91a0: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 0a 2a rmless no-ops..*
91b0: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 *.** A call to s
91c0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
91d0: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 ) is an "effecti
91e0: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 ve" call if it i
91f0: 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 s the first.** c
9200: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 all to sqlite3_s
9210: 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 hutdown() since
9220: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 the last sqlite3
9230: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 _initialize().
9240: 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 Only.** an effec
9250: 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c tive call to sql
9260: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 ite3_shutdown()
9270: 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 does any deiniti
9280: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c alization..** Al
9290: 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 20 74 6f l other calls to
92a0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
92b0: 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 n() are harmless
92c0: 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 41 no-ops..**.** A
92d0: 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 mong other thing
92e0: 73 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 s, sqlite3_initi
92f0: 61 6c 69 7a 65 28 29 20 73 68 61 6c 6c 20 69 6e alize() shall in
9300: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f voke.** sqlite3_
9310: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 os_init(). Simi
9320: 6c 61 72 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 larly, sqlite3_s
9330: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 73 68 61 hutdown().** sha
9340: 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 ll invoke sqlite
9350: 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 3_os_end()..**.*
9360: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e * The sqlite3_in
9370: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 itialize() routi
9380: 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 ne returns [SQLI
9390: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 TE_OK] on succes
93a0: 73 2e 0a 2a 2a 20 49 66 20 66 6f 72 20 73 6f 6d s..** If for som
93b0: 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 e reason, sqlite
93c0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 3_initialize() i
93d0: 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 s unable to init
93e0: 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 ialize.** the li
93f0: 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69 brary (perhaps i
9400: 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 t is unable to a
9410: 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 llocate a needed
9420: 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a resource such.*
9430: 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 * as a mutex) it
9440: 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 returns an [err
9450: 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 or code] other t
9460: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e han [SQLITE_OK].
9470: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
9480: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
9490: 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 routine is calle
94a0: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 d internally by
94b0: 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 many other.** SQ
94c0: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 Lite interfaces
94d0: 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 so that an appli
94e0: 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 cation usually d
94f0: 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a oes not need to.
9500: 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 ** invoke sqlite
9510: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 3_initialize() d
9520: 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 irectly. For ex
9530: 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f ample, [sqlite3_
9540: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 open()].** calls
9550: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
9560: 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c ize() so the SQL
9570: 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c ite library will
9580: 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c be automaticall
9590: 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 y.** initialized
95a0: 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f when [sqlite3_o
95b0: 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 pen()] is called
95c0: 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 if it has not b
95d0: 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a e initialized.**
95e0: 20 61 6c 72 65 61 64 79 2e 20 20 48 6f 77 65 76 already. Howev
95f0: 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 er, if SQLite is
9600: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 compiled with t
9610: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f he [SQLITE_OMIT_
9620: 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d AUTOINIT].** com
9630: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
9640: 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d , then the autom
9650: 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 atic calls to sq
9660: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
9670: 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 ().** are omitte
9680: 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 d and the applic
9690: 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 ation must call
96a0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
96b0: 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a ze() directly.**
96c0: 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 prior to using
96d0: 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 any other SQLite
96e0: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 interface. For
96f0: 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 maximum portabi
9700: 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 lity,.** it is r
9710: 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 ecommended that
9720: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 applications alw
9730: 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 ays invoke sqlit
9740: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a e3_initialize().
9750: 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f ** directly prio
9760: 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f r to using any o
9770: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 ther SQLite inte
9780: 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 rface. Future r
9790: 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 eleases.** of SQ
97a0: 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 Lite may require
97b0: 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 this. In other
97c0: 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 words, the beha
97d0: 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a vior exhibited.*
97e0: 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 * when SQLite is
97f0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b compiled with [
9800: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f SQLITE_OMIT_AUTO
9810: 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f INIT] might beco
9820: 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c me the.** defaul
9830: 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f t behavior in so
9840: 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 me future releas
9850: 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a e of SQLite..**.
9860: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f ** The sqlite3_o
9870: 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 s_init() routine
9880: 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d does operating-
9890: 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a system specific.
98a0: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f ** initializatio
98b0: 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 n of the SQLite
98c0: 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 library. The sq
98d0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a lite3_os_end().*
98e0: 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 * routine undoes
98f0: 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 the effect of s
9900: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
9910: 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 . Typical tasks
9920: 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 .** performed by
9930: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
9940: 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 include allocati
9950: 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 on or deallocati
9960: 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 on.** of static
9970: 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 resources, initi
9980: 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f alization of glo
9990: 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a bal variables,.*
99a0: 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 * setting up a d
99b0: 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f efault [sqlite3_
99c0: 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 vfs] module, or
99d0: 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 setting up.** a
99e0: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 default configur
99f0: 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c ation using [sql
9a00: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a ite3_config()]..
9a10: 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 **.** The applic
9a20: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 ation should nev
9a30: 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 er invoke either
9a40: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
9a50: 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 ().** or sqlite3
9a60: 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 _os_end() direct
9a70: 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 ly. The applica
9a80: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 tion should only
9a90: 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 invoke.** sqlit
9aa0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
9ab0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 and sqlite3_shut
9ac0: 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c down(). The sql
9ad0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a ite3_os_init().*
9ae0: 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 * interface is c
9af0: 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 alled automatica
9b00: 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 lly by sqlite3_i
9b10: 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a nitialize() and.
9b20: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e ** sqlite3_os_en
9b30: 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 d() is called by
9b40: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
9b50: 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 n(). Appropriat
9b60: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 e.** implementat
9b70: 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 ions for sqlite3
9b80: 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 _os_init() and s
9b90: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a qlite3_os_end().
9ba0: 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 ** are built int
9bb0: 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 o SQLite when it
9bc0: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 is compiled for
9bd0: 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 Unix, Windows,
9be0: 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e or OS/2..** When
9bf0: 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 [custom builds
9c00: 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 | built for othe
9c10: 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 r platforms].**
9c20: 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 (using the [SQLI
9c30: 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 TE_OS_OTHER=1] c
9c40: 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f ompile-time.** o
9c50: 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 ption) the appli
9c60: 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 cation must supp
9c70: 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d ly a suitable im
9c80: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 plementation for
9c90: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 .** sqlite3_os_i
9ca0: 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 nit() and sqlite
9cb0: 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 3_os_end(). An
9cc0: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 application-supp
9cd0: 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e lied.** implemen
9ce0: 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 tation of sqlite
9cf0: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 3_os_init() or s
9d00: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a qlite3_os_end().
9d10: 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b ** must return [
9d20: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 SQLITE_OK] on su
9d30: 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f ccess and some o
9d40: 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 ther [error code
9d50: 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 ] upon.** failur
9d60: 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 e..*/.SQLITE_API
9d70: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 int sqlite3_ini
9d80: 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 53 tialize(void);.S
9d90: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
9da0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 lite3_shutdown(v
9db0: 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 oid);.SQLITE_API
9dc0: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f int sqlite3_os_
9dd0: 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53 51 4c 49 init(void);.SQLI
9de0: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
9df0: 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b e3_os_end(void);
9e00: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
9e10: 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 : Configuring Th
9e20: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 e SQLite Library
9e30: 20 7b 48 31 34 31 30 30 7d 20 3c 53 32 30 30 30 {H14100} <S2000
9e40: 30 3e 3c 53 33 30 32 30 30 3e 0a 2a 2a 20 45 58 0><S30200>.** EX
9e50: 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a PERIMENTAL.**.**
9e60: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e The sqlite3_con
9e70: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 fig() interface
9e80: 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 is used to make
9e90: 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 global configura
9ea0: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 tion.** changes
9eb0: 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 to SQLite in ord
9ec0: 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 er to tune SQLit
9ed0: 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 e to the specifi
9ee0: 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 c needs of.** th
9ef0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 e application.
9f00: 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 The default conf
9f10: 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 iguration is rec
9f20: 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 ommended for mos
9f30: 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e t.** application
9f40: 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f s and so this ro
9f50: 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 utine is usually
9f60: 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 not necessary.
9f70: 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 It is.** provid
9f80: 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 ed to support ra
9f90: 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 re applications
9fa0: 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 with unusual nee
9fb0: 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ds..**.** The sq
9fc0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 lite3_config() i
9fd0: 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 nterface is not
9fe0: 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 threadsafe. The
9ff0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 application.**
a000: 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 must insure that
a010: 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 no other SQLite
a020: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
a030: 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 invoked by other
a040: 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c .** threads whil
a050: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 e sqlite3_config
a060: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 () is running.
a070: 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c Furthermore, sql
a080: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a ite3_config().**
a090: 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 may only be inv
a0a0: 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 oked prior to li
a0b0: 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 brary initializa
a0c0: 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 tion using.** [s
a0d0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
a0e0: 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 e()] or after sh
a0f0: 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 utdown by [sqlit
a100: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a e3_shutdown()]..
a110: 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 ** Note, however
a120: 2c 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 63 , that sqlite3_c
a130: 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 onfig() can be c
a140: 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 alled as part of
a150: 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e the.** implemen
a160: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 tation of an app
a170: 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
a180: 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 [sqlite3_os_ini
a190: 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 t()]..**.** The
a1a0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
a1b0: 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 o sqlite3_config
a1c0: 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 () is an integer
a1d0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 .** [SQLITE_CONF
a1e0: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 IG_SINGLETHREAD
a1f0: 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 | configuration
a200: 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 option] that det
a210: 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 ermines.** what
a220: 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 property of SQLi
a230: 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 te is to be conf
a240: 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 igured. Subsequ
a250: 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a ent arguments.**
a260: 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 vary depending
a270: 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 on the [SQLITE_C
a280: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 ONFIG_SINGLETHRE
a290: 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 AD | configurati
a2a0: 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e on option].** in
a2b0: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
a2c0: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 ent..**.** When
a2d0: 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 a configuration
a2e0: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 option is set, s
a2f0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
a300: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
a310: 4f 4b 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6f OK]..** If the o
a320: 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e ption is unknown
a330: 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e or SQLite is un
a340: 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 able to set the
a350: 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 option.** then t
a360: 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 his routine retu
a370: 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b rns a non-zero [
a380: 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a error code]..**.
a390: 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
a3a0: 0a 2a 2a 20 5b 48 31 34 31 30 33 5d 20 5b 48 31 .** [H14103] [H1
a3b0: 34 31 30 36 5d 20 5b 48 31 34 31 32 30 5d 20 5b 4106] [H14120] [
a3c0: 48 31 34 31 32 33 5d 20 5b 48 31 34 31 32 36 5d H14123] [H14126]
a3d0: 20 5b 48 31 34 31 32 39 5d 20 5b 48 31 34 31 33 [H14129] [H1413
a3e0: 32 5d 20 5b 48 31 34 31 33 35 5d 0a 2a 2a 20 5b 2] [H14135].** [
a3f0: 48 31 34 31 33 38 5d 20 5b 48 31 34 31 34 31 5d H14138] [H14141]
a400: 20 5b 48 31 34 31 34 34 5d 20 5b 48 31 34 31 34 [H14144] [H1414
a410: 37 5d 20 5b 48 31 34 31 35 30 5d 20 5b 48 31 34 7] [H14150] [H14
a420: 31 35 33 5d 20 5b 48 31 34 31 35 36 5d 20 5b 48 153] [H14156] [H
a430: 31 34 31 35 39 5d 0a 2a 2a 20 5b 48 31 34 31 36 14159].** [H1416
a440: 32 5d 20 5b 48 31 34 31 36 35 5d 20 5b 48 31 34 2] [H14165] [H14
a450: 31 36 38 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 168].*/.SQLITE_A
a460: 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 PI SQLITE_EXPERI
a470: 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 MENTAL int sqlit
a480: 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e e3_config(int, .
a490: 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ..);../*.** CAPI
a4a0: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 3REF: Configure
a4b0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
a4c0: 69 6f 6e 73 20 20 7b 48 31 34 32 30 30 7d 20 3c ions {H14200} <
a4d0: 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52 S20000>.** EXPER
a4e0: 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 IMENTAL.**.** Th
a4f0: 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e e sqlite3_db_con
a500: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 fig() interface
a510: 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 is used to make
a520: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a configuration.**
a530: 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 changes to a [d
a540: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
a550: 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 on]. The interf
a560: 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 ace is similar t
a570: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f o.** [sqlite3_co
a580: 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 nfig()] except t
a590: 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 hat the changes
a5a0: 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c apply to a singl
a5b0: 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 e.** [database c
a5c0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 onnection] (spec
a5d0: 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 ified in the fir
a5e0: 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 20 20 54 st argument). T
a5f0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 64 62 he.** sqlite3_db
a600: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 _config() interf
a610: 61 63 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 ace can only be
a620: 75 73 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 used immediately
a630: 20 61 66 74 65 72 0a 2a 2a 20 74 68 65 20 64 61 after.** the da
a640: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
a650: 6e 20 69 73 20 63 72 65 61 74 65 64 20 75 73 69 n is created usi
a660: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ng [sqlite3_open
a670: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
a680: 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b _open16()], or [
a690: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
a6a0: 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 )]. .**.** The
a6b0: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
a6c0: 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f to sqlite3_db_co
a6d0: 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 nfig(D,V,...) i
a6e0: 73 20 74 68 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 s the.** configu
a6f0: 72 61 74 69 6f 6e 20 76 65 72 62 20 2d 20 61 6e ration verb - an
a700: 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 integer code th
a710: 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 at indicates wha
a720: 74 0a 2a 2a 20 61 73 70 65 63 74 20 6f 66 20 74 t.** aspect of t
a730: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
a740: 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e nection] is bein
a750: 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a g configured..**
a760: 20 54 68 65 20 6f 6e 6c 79 20 63 68 6f 69 63 65 The only choice
a770: 20 66 6f 72 20 74 68 69 73 20 76 61 6c 75 65 20 for this value
a780: 69 73 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e is [SQLITE_DBCON
a790: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a FIG_LOOKASIDE]..
a7a0: 2a 2a 20 4e 65 77 20 76 65 72 62 73 20 61 72 65 ** New verbs are
a7b0: 20 6c 69 6b 65 6c 79 20 74 6f 20 62 65 20 61 64 likely to be ad
a7c0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 ded in future re
a7d0: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 leases of SQLite
a7e0: 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 ..** Additional
a7f0: 61 72 67 75 6d 65 6e 74 73 20 64 65 70 65 6e 64 arguments depend
a800: 20 6f 6e 20 74 68 65 20 76 65 72 62 2e 0a 2a 2a on the verb..**
a810: 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
a820: 3a 0a 2a 2a 20 5b 48 31 34 32 30 33 5d 20 5b 48 :.** [H14203] [H
a830: 31 34 32 30 36 5d 20 5b 48 31 34 32 30 39 5d 20 14206] [H14209]
a840: 5b 48 31 34 32 31 32 5d 20 5b 48 31 34 32 31 35 [H14212] [H14215
a850: 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
a860: 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e SQLITE_EXPERIMEN
a870: 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f TAL int sqlite3_
a880: 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 db_config(sqlite
a890: 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3*, int op, ...)
a8a0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
a8b0: 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 F: Memory Alloca
a8c0: 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b 48 tion Routines {H
a8d0: 31 30 31 35 35 7d 20 3c 53 32 30 31 32 30 3e 0a 10155} <S20120>.
a8e0: 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a ** EXPERIMENTAL.
a8f0: 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 **.** An instanc
a900: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 e of this object
a910: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 defines the int
a920: 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 erface between S
a930: 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 QLite.** and low
a940: 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c -level memory al
a950: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 location routine
a960: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 s..**.** This ob
a970: 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 ject is used in
a980: 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 only one place i
a990: 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 n the SQLite int
a9a0: 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 erface..** A poi
a9b0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 nter to an insta
a9c0: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 nce of this obje
a9d0: 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 ct is the argume
a9e0: 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 nt to.** [sqlite
a9f0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 3_config()] when
aa00: 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 the configurati
aa10: 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 on option is.**
aa20: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
aa30: 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 ALLOC] or [SQLIT
aa40: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c E_CONFIG_GETMALL
aa50: 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 OC]. .** By cre
aa60: 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 ating an instanc
aa70: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 e of this object
aa80: 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 .** and passing
aa90: 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 it to [sqlite3_c
aaa0: 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 onfig]([SQLITE_C
aab0: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a ONFIG_MALLOC]).*
aac0: 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 * during configu
aad0: 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 ration, an appli
aae0: 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 cation can speci
aaf0: 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 fy an alternativ
ab00: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f e.** memory allo
ab10: 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d cation subsystem
ab20: 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 for SQLite to u
ab30: 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 se for all of it
ab40: 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d s.** dynamic mem
ab50: 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a ory needs..**.**
ab60: 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 Note that SQLit
ab70: 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 e comes with sev
ab80: 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d eral [built-in m
ab90: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 emory allocators
aba0: 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 ].** that are pe
abb0: 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 rfectly adequate
abc0: 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 for the overwhe
abd0: 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f lming majority o
abe0: 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a f applications.*
abf0: 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 * and that this
ac00: 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 object is only u
ac10: 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 seful to a tiny
ac20: 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c minority of appl
ac30: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 ications.** with
ac40: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d specialized mem
ac50: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
ac60: 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 equirements. Th
ac70: 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 is object is.**
ac80: 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 also used during
ac90: 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 testing of SQLi
aca0: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 te in order to s
acb0: 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e pecify an altern
acc0: 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 ative.** memory
acd0: 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 allocator that s
ace0: 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 imulates memory
acf0: 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f out-of-memory co
ad00: 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f nditions in.** o
ad10: 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 rder to verify t
ad20: 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 hat SQLite recov
ad30: 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 ers gracefully f
ad40: 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 rom such.** cond
ad50: 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 itions..**.** Th
ad60: 65 20 78 4d 61 6c 6c 6f 63 20 61 6e 64 20 78 46 e xMalloc and xF
ad70: 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 ree methods must
ad80: 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a work like the.*
ad90: 2a 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 * malloc() and f
ada0: 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 ree() functions
adb0: 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 from the standar
adc0: 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 d C library..**
add0: 54 68 65 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 The xRealloc met
ade0: 68 6f 64 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 hod must work li
adf0: 6b 65 20 72 65 61 6c 6c 6f 63 28 29 20 66 72 6f ke realloc() fro
ae00: 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 m the standard C
ae10: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 77 69 74 68 library.** with
ae20: 20 74 68 65 20 65 78 63 65 70 74 69 6f 6e 20 74 the exception t
ae30: 68 61 74 20 69 66 20 74 68 65 20 73 65 63 6f 6e hat if the secon
ae40: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 52 d argument to xR
ae50: 65 61 6c 6c 6f 63 20 69 73 20 7a 65 72 6f 2c 0a ealloc is zero,.
ae60: 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 6d 75 73 74 ** xRealloc must
ae70: 20 62 65 20 61 20 6e 6f 2d 6f 70 20 2d 20 69 74 be a no-op - it
ae80: 20 6d 75 73 74 20 6e 6f 74 20 70 65 72 66 6f 72 must not perfor
ae90: 6d 20 61 6e 79 20 61 6c 6c 6f 63 61 74 69 6f 6e m any allocation
aea0: 20 6f 72 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 or.** deallocat
aeb0: 69 6f 6e 2e 20 20 53 51 4c 69 74 65 20 67 75 61 ion. SQLite gua
aec0: 72 61 6e 74 65 65 64 73 20 74 68 61 74 20 74 68 ranteeds that th
aed0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
aee0: 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 t to.** xRealloc
aef0: 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c is always a val
af00: 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 ue returned by a
af10: 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 prior call to x
af20: 52 6f 75 6e 64 75 70 2e 0a 2a 2a 20 41 6e 64 20 Roundup..** And
af30: 73 6f 20 69 6e 20 63 61 73 65 73 20 77 68 65 72 so in cases wher
af40: 65 20 78 52 6f 75 6e 64 75 70 20 61 6c 77 61 79 e xRoundup alway
af50: 73 20 72 65 74 75 72 6e 73 20 61 20 70 6f 73 69 s returns a posi
af60: 74 69 76 65 20 6e 75 6d 62 65 72 2c 0a 2a 2a 20 tive number,.**
af70: 78 52 65 61 6c 6c 6f 63 20 63 61 6e 20 70 65 72 xRealloc can per
af80: 66 6f 72 6d 20 65 78 61 63 74 6c 79 20 61 73 20 form exactly as
af90: 74 68 65 20 73 74 61 6e 64 61 72 64 20 6c 69 62 the standard lib
afa0: 72 61 72 79 20 72 65 61 6c 6c 6f 63 28 29 20 61 rary realloc() a
afb0: 6e 64 0a 2a 2a 20 73 74 69 6c 6c 20 62 65 20 69 nd.** still be i
afc0: 6e 20 63 6f 6d 70 6c 69 61 6e 63 65 20 77 69 74 n compliance wit
afd0: 68 20 74 68 69 73 20 73 70 65 63 69 66 69 63 61 h this specifica
afe0: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a tion..**.** xSiz
aff0: 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 e should return
b000: 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 the allocated si
b010: 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 ze of a memory a
b020: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 llocation.** pre
b030: 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 viously obtained
b040: 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 from xMalloc or
b050: 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 xRealloc. The
b060: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a allocated size.*
b070: 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c * is always at l
b080: 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74 east as big as t
b090: 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a he requested siz
b0a0: 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 e but may be lar
b0b0: 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ger..**.** The x
b0c0: 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 Roundup method r
b0d0: 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c eturns what woul
b0e0: 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 d be the allocat
b0f0: 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 ed size of.** a
b100: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
b110: 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 n given a partic
b120: 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73 ular requested s
b130: 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 ize. Most memor
b140: 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 y.** allocators
b150: 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 round up memory
b160: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c allocations at l
b170: 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 east to the next
b180: 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 multiple.** of
b190: 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 8. Some allocat
b1a0: 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 ors round up to
b1b0: 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c a larger multipl
b1c0: 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 e or to a power
b1d0: 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d of 2..** Every m
b1e0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
b1f0: 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 request coming
b200: 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 in through [sqli
b210: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a te3_malloc()].**
b220: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 or [sqlite3_rea
b230: 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 lloc()] first ca
b240: 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 lls xRoundup. I
b250: 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 f xRoundup retur
b260: 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 ns 0, .** that c
b270: 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 auses the corres
b280: 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 ponding memory a
b290: 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 llocation to fai
b2a0: 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e l..**.** The xIn
b2b0: 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 it method initia
b2c0: 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 lizes the memory
b2d0: 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f allocator. (Fo
b2e0: 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 r example,.** it
b2f0: 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 might allocate
b300: 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 any require mute
b310: 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a xes or initializ
b320: 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a e internal data.
b330: 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 ** structures.
b340: 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 The xShutdown me
b350: 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 thod is invoked
b360: 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a (indirectly) by.
b370: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 ** [sqlite3_shut
b380: 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 down()] and shou
b390: 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e ld deallocate an
b3a0: 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 y resources acqu
b3b0: 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 ired.** by xInit
b3c0: 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20 . The pAppData
b3d0: 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 pointer is used
b3e0: 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 as the only para
b3f0: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 meter to.** xIni
b400: 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e t and xShutdown.
b410: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f .**.** SQLite ho
b420: 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f lds the [SQLITE_
b430: 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 MUTEX_STATIC_MAS
b440: 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 TER] mutex when
b450: 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 it invokes.** th
b460: 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 e xInit method,
b470: 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 so the xInit met
b480: 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 hod need not be
b490: 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 threadsafe. The
b4a0: 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 .** xShutdown me
b4b0: 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c thod is only cal
b4c0: 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 led from [sqlite
b4d0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 3_shutdown()] so
b4e0: 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 it does.** not
b4f0: 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 need to be threa
b500: 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 dsafe either. F
b510: 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 or all other met
b520: 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 hods, SQLite.**
b530: 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 holds the [SQLIT
b540: 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d E_MUTEX_STATIC_M
b550: 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e EM] mutex as lon
b560: 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c g as the.** [SQL
b570: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 ITE_CONFIG_MEMST
b580: 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 ATUS] configurat
b590: 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 ion option is tu
b5a0: 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a rned on (which.*
b5b0: 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75 * it is by defau
b5c0: 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d lt) and so the m
b5d0: 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d ethods are autom
b5e0: 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 atically seriali
b5f0: 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c zed..** However,
b600: 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 if [SQLITE_CONF
b610: 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 IG_MEMSTATUS] is
b620: 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 disabled, then
b630: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 the other.** met
b640: 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 hods must be thr
b650: 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 eadsafe or else
b660: 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 make their own a
b670: 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a rrangements for.
b680: 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e ** serialization
b690: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 ..**.** SQLite w
b6a0: 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 ill never invoke
b6b0: 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 xInit() more th
b6c0: 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 an once without
b6d0: 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a an intervening.*
b6e0: 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 * call to xShutd
b6f0: 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 own()..*/.typede
b700: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
b710: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c _mem_methods sql
b720: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
b730: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 ;.struct sqlite3
b740: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 _mem_methods {.
b750: 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 void *(*xMalloc
b760: 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 )(int);
b770: 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 /* Memory alloca
b780: 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f tion function */
b790: 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 . void (*xFree)
b7a0: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 (void*);
b7b0: 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f /* Free a prio
b7c0: 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a r allocation */.
b7d0: 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c void *(*xReall
b7e0: 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 oc)(void*,int);
b7f0: 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c /* Resize an al
b800: 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e location */. in
b810: 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a t (*xSize)(void*
b820: 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 ); /*
b830: 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 Return the size
b840: 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e of an allocation
b850: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 */. int (*xRou
b860: 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 ndup)(int);
b870: 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 /* Round up
b880: 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f request size to
b890: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 allocation size
b8a0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 */. int (*xIni
b8b0: 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 t)(void*);
b8c0: 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 /* Initiali
b8d0: 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c ze the memory al
b8e0: 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 locator */. voi
b8f0: 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 d (*xShutdown)(v
b900: 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 oid*); /* D
b910: 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 einitialize the
b920: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
b930: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 */. void *pApp
b940: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 Data;
b950: 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 /* Argument
b960: 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 to xInit() and
b970: 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d xShutdown() */.}
b980: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
b990: 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e F: Configuration
b9a0: 20 4f 70 74 69 6f 6e 73 20 7b 48 31 30 31 36 30 Options {H10160
b9b0: 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58 } <S20000>.** EX
b9c0: 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a PERIMENTAL.**.**
b9d0: 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 These constants
b9e0: 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 are the availab
b9f0: 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 le integer confi
ba00: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 guration options
ba10: 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 that.** can be
ba20: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 passed as the fi
ba30: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
ba40: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e the [sqlite3_con
ba50: 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 fig()] interface
ba60: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 ..**.** New conf
ba70: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
ba80: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 s may be added i
ba90: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
baa0: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 s of SQLite..**
bab0: 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 Existing configu
bac0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d ration options m
bad0: 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 ight be disconti
bae0: 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 nued. Applicati
baf0: 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 ons.** should ch
bb00: 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 eck the return c
bb10: 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ode from [sqlite
bb20: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 3_config()] to m
bb30: 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a ake sure that.**
bb40: 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 the call worked
bb50: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f . The [sqlite3_
bb60: 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 config()] interf
bb70: 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ace will return
bb80: 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 a.** non-zero [e
bb90: 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 rror code] if a
bba0: 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 discontinued or
bbb0: 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 unsupported conf
bbc0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
bbd0: 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a .** is invoked..
bbe0: 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 **.** <dl>.** <d
bbf0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
bc00: 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 SINGLETHREAD</dt
bc10: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 >.** <dd>There a
bc20: 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 re no arguments
bc30: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 to this option.
bc40: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 This option dis
bc50: 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 ables.** all mut
bc60: 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 exing and puts S
bc70: 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 QLite into a mod
bc80: 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f e where it can o
bc90: 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 nly be used.** b
bca0: 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 y a single threa
bcb0: 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 d.</dd>.**.** <d
bcc0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
bcd0: 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e MULTITHREAD</dt>
bce0: 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 .** <dd>There ar
bcf0: 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 e no arguments t
bd00: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 o this option.
bd10: 54 68 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 This option disa
bd20: 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 bles.** mutexing
bd30: 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f on [database co
bd40: 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 nnection] and [p
bd50: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
bd60: 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 t] objects..** T
bd70: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 he application i
bd80: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f s responsible fo
bd90: 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 r serializing ac
bda0: 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 cess to.** [data
bdb0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
bdc0: 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 ] and [prepared
bdd0: 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 statements]. Bu
bde0: 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a t other mutexes.
bdf0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 ** are enabled s
be00: 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 o that SQLite wi
be10: 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 ll be safe to us
be20: 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 e in a multi-thr
be30: 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e eaded.** environ
be40: 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 ment as long as
be50: 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 no two threads a
be60: 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 ttempt to use th
be70: 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 e same.** [datab
be80: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
be90: 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 at the same time
bea0: 2e 20 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 . See the [thre
beb0: 61 64 69 6e 67 20 6d 6f 64 65 5d 0a 2a 2a 20 64 ading mode].** d
bec0: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 ocumentation for
bed0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f additional info
bee0: 72 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a rmation.</dd>.**
bef0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
bf00: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 ONFIG_SERIALIZED
bf10: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
bf20: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 re are no argume
bf30: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 nts to this opti
bf40: 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e on. This option
bf50: 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 enables.** all
bf60: 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e mutexes includin
bf70: 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a g the recursive.
bf80: 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 ** mutexes on [d
bf90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
bfa0: 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 on] and [prepare
bfb0: 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a d statement] obj
bfc0: 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 ects..** In this
bfd0: 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 mode (which is
bfe0: 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e the default when
bff0: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
c000: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c led with.** [SQL
c010: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 ITE_THREADSAFE=1
c020: 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 ]) the SQLite li
c030: 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c brary will itsel
c040: 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 f serialize acce
c050: 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 ss.** to [databa
c060: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 se connections]
c070: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 and [prepared st
c080: 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 atements] so tha
c090: 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 t the.** applica
c0a0: 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 tion is free to
c0b0: 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 use the same [da
c0c0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
c0d0: 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d n] or the.** sam
c0e0: 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
c0f0: 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 ement] in differ
c100: 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 ent threads at t
c110: 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a he same time..**
c120: 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 See the [thread
c130: 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 ing mode] docume
c140: 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 ntation for addi
c150: 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 tional informati
c160: 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c on.</dd>.**.** <
c170: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
c180: 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 _MALLOC</dt>.**
c190: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 <dd>This option
c1a0: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
c1b0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
c1c0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
c1d0: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 .** instance of
c1e0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d the [sqlite3_mem
c1f0: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 _methods] struct
c200: 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 ure. The argume
c210: 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 nt specifies.**
c220: 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d alternative low-
c230: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c level memory all
c240: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 ocation routines
c250: 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 to be used in p
c260: 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d lace of.** the m
c270: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
c280: 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 routines built
c290: 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64 into SQLite.</dd
c2a0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
c2b0: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c TE_CONFIG_GETMAL
c2c0: 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e LOC</dt>.** <dd>
c2d0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
c2e0: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
c2f0: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 ent which is a p
c300: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 ointer to an.**
c310: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 instance of the
c320: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 [sqlite3_mem_met
c330: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e hods] structure.
c340: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d The [sqlite3_m
c350: 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 em_methods].** s
c360: 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c tructure is fill
c370: 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 ed with the curr
c380: 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 ently defined me
c390: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
c3a0: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 routines..** Thi
c3b0: 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 s option can be
c3c0: 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 used to overload
c3d0: 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d the default mem
c3e0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a ory allocation.*
c3f0: 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 * routines with
c400: 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73 a wrapper that s
c410: 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 imulations memor
c420: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 y allocation fai
c430: 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b lure or.** track
c440: 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 s memory usage,
c450: 66 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 for example.</dd
c460: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
c470: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 TE_CONFIG_MEMSTA
c480: 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e TUS</dt>.** <dd>
c490: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
c4a0: 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e s single argumen
c4b0: 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 t of type int, i
c4c0: 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 nterpreted as a
c4d0: 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 .** boolean, whi
c4e0: 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 ch enables or di
c4f0: 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 sables the colle
c500: 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 ction of memory
c510: 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 allocation .** s
c520: 74 61 74 69 73 74 69 63 73 2e 20 57 68 65 6e 20 tatistics. When
c530: 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f disabled, the fo
c540: 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 llowing SQLite i
c550: 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 nterfaces become
c560: 20 0a 2a 2a 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 .** non-operati
c570: 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a onal:.** <ul>.
c580: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 ** <li> [sqlit
c590: 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 e3_memory_used()
c5a0: 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c ].** <li> [sql
c5b0: 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 ite3_memory_high
c5c0: 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c water()].** <l
c5d0: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 i> [sqlite3_soft
c5e0: 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a _heap_limit()].*
c5f0: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 * <li> [sqlite
c600: 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 3_status()].**
c610: 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a </ul>.** </dd>.
c620: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
c630: 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c _CONFIG_SCRATCH<
c640: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 /dt>.** <dd>This
c650: 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 option specifie
c660: 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 s a static memor
c670: 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 y buffer that SQ
c680: 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 Lite can use for
c690: 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f .** scratch memo
c6a0: 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 ry. There are t
c6b0: 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 hree arguments:
c6c0: 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d A pointer an 8-
c6d0: 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 byte.** aligned
c6e0: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 memory buffer fr
c6f0: 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72 om which the scr
c700: 61 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 ach allocations
c710: 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e will be.** drawn
c720: 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 , the size of ea
c730: 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 ch scratch alloc
c740: 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 ation (sz),.** a
c750: 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e nd the maximum n
c760: 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 umber of scratch
c770: 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 allocations (N)
c780: 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 . The sz.** arg
c790: 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 ument must be a
c7a0: 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 20 multiple of 16.
c7b0: 54 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 The sz parameter
c7c0: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 66 65 77 should be a few
c7d0: 20 62 79 74 65 73 0a 2a 2a 20 6c 61 72 67 65 72 bytes.** larger
c7e0: 20 74 68 61 6e 20 74 68 65 20 61 63 74 75 61 6c than the actual
c7f0: 20 73 63 72 61 74 63 68 20 73 70 61 63 65 20 72 scratch space r
c800: 65 71 75 69 72 65 64 20 64 75 65 20 74 6f 20 69 equired due to i
c810: 6e 74 65 72 6e 61 6c 20 6f 76 65 72 68 65 61 64 nternal overhead
c820: 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 ..** The first a
c830: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 rgument should p
c840: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 ointer to an 8-b
c850: 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 yte aligned buff
c860: 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 er.** of at leas
c870: 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 t sz*N bytes of
c880: 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 memory..** SQLit
c890: 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f e will use no mo
c8a0: 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 re than one scra
c8b0: 74 63 68 20 62 75 66 66 65 72 20 61 74 20 6f 6e tch buffer at on
c8c0: 63 65 20 70 65 72 20 74 68 72 65 61 64 2c 20 73 ce per thread, s
c8d0: 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 o.** N should be
c8e0: 20 73 65 74 20 74 6f 20 74 68 65 20 65 78 70 65 set to the expe
c8f0: 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d cted maximum num
c900: 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 20 ber of threads.
c910: 20 54 68 65 20 73 7a 0a 2a 2a 20 70 61 72 61 6d The sz.** param
c920: 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 36 eter should be 6
c930: 20 74 69 6d 65 73 20 74 68 65 20 73 69 7a 65 20 times the size
c940: 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 of the largest d
c950: 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a atabase page siz
c960: 65 2e 0a 2a 2a 20 53 63 72 61 74 63 68 20 62 75 e..** Scratch bu
c970: 66 66 65 72 73 20 61 72 65 20 75 73 65 64 20 61 ffers are used a
c980: 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 62 74 s part of the bt
c990: 72 65 65 20 62 61 6c 61 6e 63 65 20 6f 70 65 72 ree balance oper
c9a0: 61 74 69 6f 6e 2e 20 20 49 66 0a 2a 2a 20 54 68 ation. If.** Th
c9b0: 65 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65 72 e btree balancer
c9c0: 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 needs additiona
c9d0: 6c 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 l memory beyond
c9e0: 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 what is provided
c9f0: 20 62 79 0a 2a 2a 20 73 63 72 61 74 63 68 20 62 by.** scratch b
ca00: 75 66 66 65 72 73 20 6f 72 20 69 66 20 6e 6f 20 uffers or if no
ca10: 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 73 scratch buffer s
ca20: 70 61 63 65 20 69 73 20 73 70 65 63 69 66 69 65 pace is specifie
ca30: 64 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a d, then SQLite.*
ca40: 2a 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 * goes to [sqlit
ca50: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 74 6f 20 e3_malloc()] to
ca60: 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 obtain the memor
ca70: 79 20 69 74 20 6e 65 65 64 73 2e 3c 2f 64 64 3e y it needs.</dd>
ca80: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
ca90: 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 E_CONFIG_PAGECAC
caa0: 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 HE</dt>.** <dd>T
cab0: 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 his option speci
cac0: 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 fies a static me
cad0: 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 mory buffer that
cae0: 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 SQLite can use
caf0: 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 for.** the datab
cb00: 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 ase page cache w
cb10: 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 ith the default
cb20: 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 page cache imple
cb30: 6d 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 menation. .** T
cb40: 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f his configuratio
cb50: 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 n should not be
cb60: 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 used if an appli
cb70: 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 cation-define pa
cb80: 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c ge.** cache impl
cb90: 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f ementation is lo
cba0: 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 aded using the S
cbb0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
cbc0: 43 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 CHE option..** T
cbd0: 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 here are three a
cbe0: 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 rguments to this
cbf0: 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 option: A point
cc00: 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 er to 8-byte ali
cc10: 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 gned.** memory,
cc20: 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 the size of each
cc30: 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a page buffer (sz
cc40: 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 ), and the numbe
cc50: 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a r of pages (N)..
cc60: 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 ** The sz argume
cc70: 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 nt should be the
cc80: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 size of the lar
cc90: 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 gest database pa
cca0: 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f ge.** (a power o
ccb0: 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 f two between 51
ccc0: 32 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75 2 and 32768) plu
ccd0: 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61 s a little extra
cce0: 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 for each.** pag
ccf0: 65 20 68 65 61 64 65 72 2e 20 20 54 68 65 20 70 e header. The p
cd00: 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 20 age header size
cd10: 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 65 is 20 to 40 byte
cd20: 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a s depending on.*
cd30: 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 69 * the host archi
cd40: 74 65 63 74 75 72 65 2e 20 20 49 74 20 69 73 20 tecture. It is
cd50: 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 harmless, apart
cd60: 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 from the wasted
cd70: 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 memory,.** to ma
cd80: 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 ke sz a little t
cd90: 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20 66 oo large. The f
cda0: 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 irst.** argument
cdb0: 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f should point to
cdc0: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f an allocation o
cdd0: 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 f at least sz*N
cde0: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e bytes of memory.
cdf0: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 .** SQLite will
ce00: 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 use the memory p
ce10: 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66 rovided by the f
ce20: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
ce30: 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 satisfy its.**
ce40: 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 memory needs for
ce50: 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 the first N pag
ce60: 65 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20 es that it adds
ce70: 74 6f 20 63 61 63 68 65 2e 20 20 49 66 20 61 64 to cache. If ad
ce80: 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 ditional.** page
ce90: 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 cache memory is
cea0: 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 needed beyond w
ceb0: 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 hat is provided
cec0: 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 by this option,
ced0: 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 then.** SQLite g
cee0: 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f oes to [sqlite3_
cef0: 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 malloc()] for th
cf00: 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f e additional sto
cf10: 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 rage space..** T
cf20: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
cf30: 6e 20 6d 69 67 68 74 20 75 73 65 20 6f 6e 65 20 n might use one
cf40: 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 4e or more of the N
cf50: 20 62 75 66 66 65 72 73 20 74 6f 20 68 6f 6c 64 buffers to hold
cf60: 20 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 63 63 6f .** memory acco
cf70: 75 6e 74 69 6e 67 20 69 6e 66 6f 72 6d 61 74 69 unting informati
cf80: 6f 6e 2e 20 54 68 65 20 70 6f 69 6e 74 65 72 20 on. The pointer
cf90: 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 in the first arg
cfa0: 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 ument must.** be
cfb0: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 aligned to an 8
cfc0: 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f -byte boundary o
cfd0: 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 r subsequent beh
cfe0: 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a avior of SQLite.
cff0: 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 ** will be undef
d000: 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ined.</dd>.**.**
d010: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
d020: 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 IG_HEAP</dt>.**
d030: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 <dd>This option
d040: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 specifies a stat
d050: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 ic memory buffer
d060: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c that SQLite wil
d070: 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c l use.** for all
d080: 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 of its dynamic
d090: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
d0a0: 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 n needs beyond t
d0b0: 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a hose provided.**
d0c0: 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f for by [SQLITE_
d0d0: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 CONFIG_SCRATCH]
d0e0: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 and [SQLITE_CONF
d0f0: 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a IG_PAGECACHE]..*
d100: 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 * There are thre
d110: 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 e arguments: An
d120: 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 8-byte aligned p
d130: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 ointer to the me
d140: 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d mory,.** the num
d150: 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 ber of bytes in
d160: 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 the memory buffe
d170: 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d r, and the minim
d180: 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 um allocation si
d190: 7a 65 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 ze..** If the fi
d1a0: 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 rst pointer (the
d1b0: 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 memory pointer)
d1c0: 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 is NULL, then S
d1d0: 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a QLite reverts.**
d1e0: 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 to using its de
d1f0: 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c fault memory all
d200: 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 ocator (the syst
d210: 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c em malloc() impl
d220: 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 ementation),.**
d230: 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f undoing any prio
d240: 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 r invocation of
d250: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
d260: 41 4c 4c 4f 43 5d 2e 20 20 49 66 20 74 68 65 0a ALLOC]. If the.
d270: 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 ** memory pointe
d280: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e r is not NULL an
d290: 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 d either [SQLITE
d2a0: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d _ENABLE_MEMSYS3]
d2b0: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 or.** [SQLITE_E
d2c0: 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 NABLE_MEMSYS5] a
d2d0: 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e re defined, then
d2e0: 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 the alternative
d2f0: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 memory.** alloc
d300: 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 ator is engaged
d310: 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 to handle all of
d320: 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 SQLites memory
d330: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 allocation needs
d340: 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 ..** The first p
d350: 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f ointer (the memo
d360: 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 ry pointer) must
d370: 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 be aligned to a
d380: 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e n 8-byte.** boun
d390: 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 dary or subseque
d3a0: 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 nt behavior of S
d3b0: 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e QLite will be un
d3c0: 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a defined.</dd>.**
d3d0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
d3e0: 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e ONFIG_MUTEX</dt>
d3f0: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 .** <dd>This opt
d400: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
d410: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 le argument whic
d420: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 h is a pointer t
d430: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 o an.** instance
d440: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
d450: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 _mutex_methods]
d460: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 structure. The
d470: 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 argument specifi
d480: 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 es.** alternativ
d490: 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 e low-level mute
d4a0: 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 x routines to be
d4b0: 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a used in place.*
d4c0: 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 * the mutex rout
d4d0: 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 ines built into
d4e0: 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a SQLite.</dd>.**.
d4f0: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ** <dt>SQLITE_CO
d500: 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 NFIG_GETMUTEX</d
d510: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f t>.** <dd>This o
d520: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
d530: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 ngle argument wh
d540: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ich is a pointer
d550: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e to an.** instan
d560: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ce of the [sqlit
d570: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 e3_mutex_methods
d580: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 ] structure. Th
d590: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 e.** [sqlite3_mu
d5a0: 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 tex_methods].**
d5b0: 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c structure is fil
d5c0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 led with the cur
d5d0: 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d rently defined m
d5e0: 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 0a 2a utex routines..*
d5f0: 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 * This option ca
d600: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 n be used to ove
d610: 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c rload the defaul
d620: 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 t mutex allocati
d630: 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 on.** routines w
d640: 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 ith a wrapper us
d650: 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 ed to track mute
d660: 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 x usage for perf
d670: 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 ormance.** profi
d680: 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c ling or testing,
d690: 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 for example.</d
d6a0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
d6b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 ITE_CONFIG_LOOKA
d6c0: 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 SIDE</dt>.** <dd
d6d0: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b >This option tak
d6e0: 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 es two arguments
d6f0: 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 that determine
d700: 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d the default.** m
d710: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
d720: 20 6c 6f 6f 6b 61 73 69 64 65 20 6f 70 74 69 6d lookaside optim
d730: 69 7a 61 74 69 6f 6e 2e 20 20 54 68 65 20 66 69 ization. The fi
d740: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 rst argument is
d750: 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 the.** size of e
d760: 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 ach lookaside bu
d770: 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 ffer slot and th
d780: 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 e second is the
d790: 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f number of.** slo
d7a0: 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 ts allocated to
d7b0: 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f each database co
d7c0: 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 nnection. This
d7d0: 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a option sets the.
d7e0: 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 ** <i>default</i
d7f0: 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 > lookaside size
d800: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 . The [SQLITE_D
d810: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 BCONFIG_LOOKASID
d820: 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 E].** verb to [s
d830: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
d840: 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 ()] can be used
d850: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f to change the lo
d860: 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 okaside.** confi
d870: 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 guration on indi
d880: 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f vidual connectio
d890: 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c ns.</dd>.**.** <
d8a0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
d8b0: 5f 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 _PCACHE</dt>.**
d8c0: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 <dd>This option
d8d0: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
d8e0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
d8f0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a a pointer to.**
d900: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 an [sqlite3_pca
d910: 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a che_methods] obj
d920: 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 ect. This objec
d930: 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 t specifies the
d940: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 interface.** to
d950: 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 a custom page ca
d960: 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 che implementati
d970: 6f 6e 2e 20 20 53 51 4c 69 74 65 20 6d 61 6b 65 on. SQLite make
d980: 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a s a copy of the.
d990: 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 ** object and us
d9a0: 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 es it for page c
d9b0: 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ache memory allo
d9c0: 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a cations.</dd>.**
d9d0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
d9e0: 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 3c ONFIG_GETPCACHE<
d9f0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 /dt>.** <dd>This
da00: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
da10: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
da20: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 which is a point
da30: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c er to an.** [sql
da40: 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 ite3_pcache_meth
da50: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 ods] object. SQ
da60: 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 Lite copies of t
da70: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 he current.** pa
da80: 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 ge cache impleme
da90: 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 ntation into tha
daa0: 74 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a t object.</dd>.*
dab0: 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 *.** </dl>.*/.#d
dac0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
dad0: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 FIG_SINGLETHREAD
dae0: 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 1 /* nil */.#
daf0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
db00: 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 NFIG_MULTITHREAD
db10: 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 2 /* nil */.
db20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
db30: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 ONFIG_SERIALIZED
db40: 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 3 /* nil */
db50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
db60: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 CONFIG_MALLOC
db70: 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 4 /* sqlit
db80: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 e3_mem_methods*
db90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
dba0: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c E_CONFIG_GETMALL
dbb0: 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c OC 5 /* sql
dbc0: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
dbd0: 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
dbe0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 ITE_CONFIG_SCRAT
dbf0: 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 CH 6 /* v
dc00: 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e oid*, int sz, in
dc10: 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 t N */.#define S
dc20: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 QLITE_CONFIG_PAG
dc30: 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a ECACHE 7 /*
dc40: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 void*, int sz,
dc50: 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 int N */.#define
dc60: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 SQLITE_CONFIG_H
dc70: 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20 EAP 8
dc80: 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 /* void*, int nB
dc90: 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a yte, int min */.
dca0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
dcb0: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 ONFIG_MEMSTATUS
dcc0: 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 9 /* boolea
dcd0: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c n */.#define SQL
dce0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 ITE_CONFIG_MUTEX
dcf0: 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 10 /* s
dd00: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
dd10: 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 hods* */.#define
dd20: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 SQLITE_CONFIG_G
dd30: 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 ETMUTEX 11
dd40: 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 /* sqlite3_mutex
dd50: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 _methods* */./*
dd60: 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 previously SQLIT
dd70: 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c E_CONFIG_CHUNKAL
dd80: 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20 LOC 12 which is
dd90: 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a now unused. */ .
dda0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
ddb0: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 ONFIG_LOOKASIDE
ddc0: 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 13 /* int in
ddd0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
dde0: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 ITE_CONFIG_PCACH
ddf0: 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 73 E 14 /* s
de00: 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 qlite3_pcache_me
de10: 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e thods* */.#defin
de20: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
de30: 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 GETPCACHE 15
de40: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 /* sqlite3_pcac
de50: 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 0a he_methods* */..
de60: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
de70: 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 Configuration Op
de80: 74 69 6f 6e 73 20 7b 48 31 30 31 37 30 7d 20 3c tions {H10170} <
de90: 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52 S20000>.** EXPER
dea0: 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 IMENTAL.**.** Th
deb0: 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 ese constants ar
dec0: 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 e the available
ded0: 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 integer configur
dee0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 ation options th
def0: 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 at.** can be pas
df00: 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e sed as the secon
df10: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 d argument to th
df20: 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f e [sqlite3_db_co
df30: 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 nfig()] interfac
df40: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e e..**.** New con
df50: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
df60: 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 ns may be added
df70: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
df80: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a es of SQLite..**
df90: 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 Existing config
dfa0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 uration options
dfb0: 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 might be discont
dfc0: 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 inued. Applicat
dfd0: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 ions.** should c
dfe0: 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 heck the return
dff0: 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 code from [sqlit
e000: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 e3_db_config()]
e010: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 to make sure tha
e020: 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f t.** the call wo
e030: 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 rked. The [sqli
e040: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d te3_db_config()]
e050: 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 interface will
e060: 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d return a.** non-
e070: 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 zero [error code
e080: 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e ] if a discontin
e090: 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 ued or unsupport
e0a0: 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ed configuration
e0b0: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e option.** is in
e0c0: 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c voked..**.** <dl
e0d0: 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f >.** <dt>SQLITE_
e0e0: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 DBCONFIG_LOOKASI
e0f0: 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 DE</dt>.** <dd>T
e100: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
e110: 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 three additiona
e120: 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 l arguments that
e130: 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a determine the .
e140: 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 ** [lookaside me
e150: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 mory allocator]
e160: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f configuration fo
e170: 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 r the [database
e180: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 connection]..**
e190: 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
e1a0: 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61 nt (the third pa
e1b0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
e1c0: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d te3_db_config()]
e1d0: 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 is a.** pointer
e1e0: 20 74 6f 20 61 6e 20 6d 65 6d 6f 72 79 20 62 75 to an memory bu
e1f0: 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 ffer to use for
e200: 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 lookaside memory
e210: 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 ..** The first a
e220: 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 4e rgument may be N
e230: 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 ULL in which cas
e240: 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c e SQLite will al
e250: 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f locate the.** lo
e260: 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69 okaside buffer i
e270: 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c tself using [sql
e280: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 ite3_malloc()].
e290: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 The second argu
e2a0: 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 ment is the.** s
e2b0: 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b ize of each look
e2c0: 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f aside buffer slo
e2d0: 74 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 t and the third
e2e0: 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 argument is the
e2f0: 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f number of.** slo
e300: 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 ts. The size of
e310: 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 the buffer in t
e320: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
e330: 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 t must be greate
e340: 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 r than.** or equ
e350: 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 al to the produc
e360: 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 t of the second
e370: 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 and third argume
e380: 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 nts. The buffer
e390: 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 .** must be alig
e3a0: 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 ned to an 8-byte
e3b0: 20 62 6f 75 6e 64 61 72 79 2e 20 20 49 66 20 74 boundary. If t
e3c0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
e3d0: 6e 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 61 20 6d nt is not.** a m
e3e0: 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 ultiple of 8, it
e3f0: 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 20 72 is internally r
e400: 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 ounded down to t
e410: 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 0a he next smaller.
e420: 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 ** multiple of 8
e430: 2e 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 . See also: [SQ
e440: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b LITE_CONFIG_LOOK
e450: 41 53 49 44 45 5d 3c 2f 64 64 3e 0a 2a 2a 0a 2a ASIDE]</dd>.**.*
e460: 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 * </dl>.*/.#defi
e470: 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 ne SQLITE_DBCONF
e480: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 IG_LOOKASIDE
e490: 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 1001 /* void* i
e4a0: 6e 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a nt int */.../*.*
e4b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 * CAPI3REF: Enab
e4c0: 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 le Or Disable Ex
e4d0: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f tended Result Co
e4e0: 64 65 73 20 7b 48 31 32 32 30 30 7d 20 3c 53 31 des {H12200} <S1
e4f0: 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 0700>.**.** The
e500: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
e510: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 _result_codes()
e520: 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 routine enables
e530: 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a or disables the.
e540: 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 ** [extended res
e550: 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 ult codes] featu
e560: 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 54 68 re of SQLite. Th
e570: 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c e extended resul
e580: 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 t.** codes are d
e590: 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 isabled by defau
e5a0: 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 lt for historica
e5b0: 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 l compatibility
e5c0: 63 6f 6e 73 69 64 65 72 61 74 69 6f 6e 73 2e 0a considerations..
e5d0: 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
e5e0: 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 30 31 5d 20 ts:.** [H12201]
e5f0: 5b 48 31 32 32 30 32 5d 0a 2a 2f 0a 53 51 4c 49 [H12202].*/.SQLI
e600: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
e610: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 e3_extended_resu
e620: 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 lt_codes(sqlite3
e630: 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a *, int onoff);..
e640: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
e650: 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 Last Insert Rowi
e660: 64 20 7b 48 31 32 32 32 30 7d 20 3c 53 31 30 37 d {H12220} <S107
e670: 30 30 3e 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 00>.**.** Each e
e680: 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 ntry in an SQLit
e690: 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e e table has a un
e6a0: 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e ique 64-bit sign
e6b0: 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 ed.** integer ke
e6c0: 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f y called the [RO
e6d0: 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 WID | "rowid"].
e6e0: 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 The rowid is alw
e6f0: 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a ays available.**
e700: 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 as an undeclare
e710: 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 d column named R
e720: 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 OWID, OID, or _R
e730: 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 OWID_ as long as
e740: 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 those.** names
e750: 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 are not also use
e760: 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 d by explicitly
e770: 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 declared columns
e780: 2e 20 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c . If.** the tabl
e790: 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f e has a column o
e7a0: 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 f type [INTEGER
e7b0: 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 PRIMARY KEY] the
e7c0: 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a n that column.**
e7d0: 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 is another alia
e7e0: 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e s for the rowid.
e7f0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
e800: 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ine returns the
e810: 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 6d [rowid] of the m
e820: 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 ost recent.** su
e830: 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 ccessful [INSERT
e840: 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 ] into the datab
e850: 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 ase from the [da
e860: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
e870: 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 n].** in the fir
e880: 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 st argument. If
e890: 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b no successful [
e8a0: 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 INSERT]s.** have
e8b0: 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f ever occurred o
e8c0: 6e 20 74 68 61 74 20 64 61 74 61 62 61 73 65 20 n that database
e8d0: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f connection, zero
e8e0: 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
e8f0: 0a 2a 2a 20 49 66 20 61 6e 20 5b 49 4e 53 45 52 .** If an [INSER
e900: 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e T] occurs within
e910: 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e a trigger, then
e920: 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 the [rowid] of
e930: 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 the inserted.**
e940: 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 row is returned
e950: 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 by this routine
e960: 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 as long as the t
e970: 72 69 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e rigger is runnin
e980: 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 g..** But once t
e990: 68 65 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 he trigger termi
e9a0: 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 nates, the value
e9b0: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 returned by thi
e9c0: 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 s routine.** rev
e9d0: 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 erts to the last
e9e0: 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 value inserted
e9f0: 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 before the trigg
ea00: 65 72 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 er fired..**.**
ea10: 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 An [INSERT] that
ea20: 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 fails due to a
ea30: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 constraint viola
ea40: 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a tion is not a.**
ea50: 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 successful [INS
ea60: 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f ERT] and does no
ea70: 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c t change the val
ea80: 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 ue returned by t
ea90: 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 his.** routine.
eaa0: 20 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 Thus INSERT OR
eab0: 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 FAIL, INSERT OR
eac0: 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f IGNORE, INSERT O
ead0: 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 R ROLLBACK,.** a
eae0: 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f nd INSERT OR ABO
eaf0: 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 RT make no chang
eb00: 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e es to the return
eb10: 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a value of this.*
eb20: 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 * routine when t
eb30: 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 heir insertion f
eb40: 61 69 6c 73 2e 20 20 57 68 65 6e 20 49 4e 53 45 ails. When INSE
eb50: 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a RT OR REPLACE.**
eb60: 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f encounters a co
eb70: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 nstraint violati
eb80: 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 on, it does not
eb90: 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e fail. The.** IN
eba0: 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 SERT continues t
ebb0: 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 o completion aft
ebc0: 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 er deleting rows
ebd0: 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 that caused.**
ebe0: 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 the constraint p
ebf0: 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 roblem so INSERT
ec00: 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c OR REPLACE will
ec10: 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a always change.*
ec20: 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c * the return val
ec30: 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 ue of this inter
ec40: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 face..**.** For
ec50: 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 the purposes of
ec60: 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e this routine, an
ec70: 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e [INSERT] is con
ec80: 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 sidered to.** be
ec90: 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e successful even
eca0: 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 if it is subseq
ecb0: 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 uently rolled ba
ecc0: 63 6b 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 ck..**.** Requir
ecd0: 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 ements:.** [H122
ece0: 32 31 5d 20 5b 48 31 32 32 32 33 5d 0a 2a 2a 0a 21] [H12223].**.
ecf0: 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 ** If a separate
ed00: 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 thread performs
ed10: 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 a new [INSERT]
ed20: 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 on the same.** d
ed30: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
ed40: 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 on while the [sq
ed50: 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 lite3_last_inser
ed60: 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 t_rowid()].** fu
ed70: 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e nction is runnin
ed80: 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 g and thus chang
ed90: 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 es the last inse
eda0: 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 rt [rowid],.** t
edb0: 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 hen the value re
edc0: 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
edd0: 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 e3_last_insert_r
ede0: 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e owid()] is.** un
edf0: 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 predictable and
ee00: 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 might not equal
ee10: 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f either the old o
ee20: 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 r the new.** las
ee30: 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d t insert [rowid]
ee40: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
ee50: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 sqlite3_int64 sq
ee60: 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 lite3_last_inser
ee70: 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a t_rowid(sqlite3*
ee80: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
ee90: 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 EF: Count The Nu
eea0: 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 mber Of Rows Mod
eeb0: 69 66 69 65 64 20 7b 48 31 32 32 34 30 7d 20 3c ified {H12240} <
eec0: 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S10600>.**.** Th
eed0: 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 is function retu
eee0: 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
eef0: 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 f database rows
ef00: 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 that were change
ef10: 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 d.** or inserted
ef20: 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 or deleted by t
ef30: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 he most recently
ef40: 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 completed SQL s
ef50: 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 tatement.** on t
ef60: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
ef70: 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 nection] specifi
ef80: 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 ed by the first
ef90: 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 4f 6e parameter..** On
efa0: 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 ly changes that
efb0: 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 are directly spe
efc0: 63 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 cified by the [I
efd0: 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d NSERT], [UPDATE]
efe0: 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d ,.** or [DELETE]
eff0: 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 statement are c
f000: 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 ounted. Auxilia
f010: 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 ry changes cause
f020: 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 d by.** triggers
f030: 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 are not counted
f040: 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 . Use the [sqlit
f050: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e3_total_changes
f060: 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 ()] function.**
f070: 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61 to find the tota
f080: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e l number of chan
f090: 67 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 ges including ch
f0a0: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 anges caused by
f0b0: 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 triggers..**.**
f0c0: 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 Changes to a vie
f0d0: 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c w that are simul
f0e0: 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 ated by an [INST
f0f0: 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a EAD OF trigger].
f100: 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 ** are not count
f110: 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 ed. Only real t
f120: 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 able changes are
f130: 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 counted..**.**
f140: 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69 A "row change" i
f150: 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20 s a change to a
f160: 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 single row of a
f170: 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 single table.**
f180: 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53 caused by an INS
f190: 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 ERT, DELETE, or
f1a0: 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 UPDATE statement
f1b0: 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 . Rows that.**
f1c0: 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73 are changed as s
f1d0: 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b ide effects of [
f1e0: 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 REPLACE] constra
f1f0: 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a int resolution,.
f200: 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f ** rollback, ABO
f210: 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b RT processing, [
f220: 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20 DROP TABLE], or
f230: 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 by any other.**
f240: 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f mechanisms do no
f250: 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 t count as direc
f260: 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a t row changes..*
f270: 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20 *.** A "trigger
f280: 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73 63 context" is a sc
f290: 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e ope of execution
f2a0: 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64 that begins and
f2b0: 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68 .** ends with th
f2c0: 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 5b 43 e script of a [C
f2d0: 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 REATE TRIGGER |
f2e0: 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f trigger]. .** Mo
f2f0: 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 st SQL statement
f300: 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 s are.** evaluat
f310: 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e ed outside of an
f320: 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69 73 y trigger. This
f330: 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76 is the "top lev
f340: 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 el".** trigger c
f350: 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74 72 ontext. If a tr
f360: 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d igger fires from
f370: 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 the top level,
f380: 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72 a.** new trigger
f390: 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65 context is ente
f3a0: 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72 61 red for the dura
f3b0: 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 tion of that one
f3c0: 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75 .** trigger. Su
f3d0: 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74 65 btriggers create
f3e0: 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 subcontexts for
f3f0: 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e their duration.
f400: 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 5b .**.** Calling [
f410: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 sqlite3_exec()]
f420: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 or [sqlite3_step
f430: 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 ()] recursively
f440: 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 does.** not crea
f450: 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 te a new trigger
f460: 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 context..**.**
f470: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 This function re
f480: 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
f490: 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 of direct row c
f4a0: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a hanges in the.**
f4b0: 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 most recent INS
f4c0: 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 ERT, UPDATE, or
f4d0: 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 DELETE statement
f4e0: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 within the same
f4f0: 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 .** trigger cont
f500: 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 75 73 2c ext..**.** Thus,
f510: 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f when called fro
f520: 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c m the top level,
f530: 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 this function r
f540: 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 eturns the.** nu
f550: 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 mber of changes
f560: 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 in the most rece
f570: 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 nt INSERT, UPDAT
f580: 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 E, or DELETE.**
f590: 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 that also occurr
f5a0: 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65 ed at the top le
f5b0: 76 65 6c 2e 20 20 57 69 74 68 69 6e 20 74 68 65 vel. Within the
f5c0: 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 body of a trigg
f5d0: 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 er,.** the sqlit
f5e0: 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 e3_changes() int
f5f0: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 erface can be ca
f600: 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 lled to find the
f610: 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 number of.** ch
f620: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 anges in the mos
f630: 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c t recently compl
f640: 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 eted INSERT, UPD
f650: 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a ATE, or DELETE.*
f660: 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 * statement with
f670: 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 in the body of t
f680: 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e he same trigger.
f690: 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 .** However, the
f6a0: 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 number returned
f6b0: 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 does not includ
f6c0: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 e changes.** cau
f6d0: 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65 sed by subtrigge
f6e0: 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 rs since those h
f6f0: 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f ave their own co
f700: 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 ntext..**.** See
f710: 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 also the [sqlit
f720: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e3_total_changes
f730: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e ()] interface an
f740: 64 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f d the.** [count_
f750: 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2e changes pragma].
f760: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
f770: 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 34 31 5d nts:.** [H12241]
f780: 20 5b 48 31 32 32 34 33 5d 0a 2a 2a 0a 2a 2a 20 [H12243].**.**
f790: 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 If a separate th
f7a0: 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 read makes chang
f7b0: 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 es on the same d
f7c0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
f7d0: 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c on.** while [sql
f7e0: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 ite3_changes()]
f7f0: 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 is running then
f800: 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
f810: 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 ed.** is unpredi
f820: 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d ctable and not m
f830: 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 eaningful..*/.SQ
f840: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
f850: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c ite3_changes(sql
f860: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ite3*);../*.** C
f870: 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e API3REF: Total N
f880: 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f umber Of Rows Mo
f890: 64 69 66 69 65 64 20 7b 48 31 32 32 36 30 7d 20 dified {H12260}
f8a0: 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S10600>.**.** T
f8b0: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 his function ret
f8c0: 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
f8d0: 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 of row changes c
f8e0: 61 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54 aused by [INSERT
f8f0: 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f ],.** [UPDATE] o
f900: 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 r [DELETE] state
f910: 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 ments since the
f920: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
f930: 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 tion] was opened
f940: 2e 0a 2a 2a 20 54 68 65 20 63 6f 75 6e 74 20 69 ..** The count i
f950: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e ncludes all chan
f960: 67 65 73 20 66 72 6f 6d 20 61 6c 6c 20 0a 2a 2a ges from all .**
f970: 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 [CREATE TRIGGER
f980: 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 | trigger] cont
f990: 65 78 74 73 2e 20 20 48 6f 77 65 76 65 72 2c 0a exts. However,.
f9a0: 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 ** the count doe
f9b0: 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 s not include ch
f9c0: 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d anges used to im
f9d0: 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 plement [REPLACE
f9e0: 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a ] constraints,.*
f9f0: 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f * do rollbacks o
fa00: 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 r ABORT processi
fa10: 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 ng, or [DROP TAB
fa20: 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 LE] processing.
fa30: 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f The.** count do
fa40: 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 es not include r
fa50: 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74 68 61 ows of views tha
fa60: 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 t fire an [INSTE
fa70: 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a AD OF trigger],.
fa80: 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68 65 ** though if the
fa90: 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 INSTEAD OF trig
faa0: 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 ger makes change
fab0: 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 s of its own, th
fac0: 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 ose changes .**
fad0: 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 are counted..**
fae0: 54 68 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 The changes are
faf0: 63 6f 75 6e 74 65 64 20 61 73 20 73 6f 6f 6e 20 counted as soon
fb00: 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 as the statement
fb10: 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d that makes them
fb20: 20 69 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 is.** completed
fb30: 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 (when the state
fb40: 6d 65 6e 74 20 68 61 6e 64 6c 65 20 69 73 20 70 ment handle is p
fb50: 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 assed to [sqlite
fb60: 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 3_reset()] or.**
fb70: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
fb80: 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 ze()])..**.** Se
fb90: 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 e also the [sqli
fba0: 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 te3_changes()] i
fbb0: 6e 74 65 72 66 61 63 65 20 61 6e 64 20 74 68 65 nterface and the
fbc0: 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 .** [count_chang
fbd0: 65 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2a 0a 2a es pragma]..**.*
fbe0: 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
fbf0: 2a 2a 20 5b 48 31 32 32 36 31 5d 20 5b 48 31 32 ** [H12261] [H12
fc00: 32 36 33 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 263].**.** If a
fc10: 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 separate thread
fc20: 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e makes changes on
fc30: 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 the same databa
fc40: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se connection.**
fc50: 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f while [sqlite3_
fc60: 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d total_changes()]
fc70: 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e is running then
fc80: 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 the value.** re
fc90: 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 turned is unpred
fca0: 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 ictable and not
fcb0: 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 meaningful..*/.S
fcc0: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
fcd0: 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e lite3_total_chan
fce0: 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a ges(sqlite3*);..
fcf0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
fd00: 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 Interrupt A Long
fd10: 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 20 7b -Running Query {
fd20: 48 31 32 32 37 30 7d 20 3c 53 33 30 35 30 30 3e H12270} <S30500>
fd30: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 .**.** This func
fd40: 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 tion causes any
fd50: 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 pending database
fd60: 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 operation to ab
fd70: 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 ort and.** retur
fd80: 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 n at its earlies
fd90: 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 t opportunity. T
fda0: 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 his routine is t
fdb0: 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c ypically.** call
fdc0: 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 ed in response t
fdd0: 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 o a user action
fde0: 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 such as pressing
fdf0: 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 "Cancel".** or
fe00: 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 Ctrl-C where the
fe10: 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f user wants a lo
fe20: 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 ng query operati
fe30: 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d on to halt.** im
fe40: 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a mediately..**.**
fe50: 20 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 It is safe to c
fe60: 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 all this routine
fe70: 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 from a thread d
fe80: 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 ifferent from th
fe90: 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 e.** thread that
fea0: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 is currently ru
feb0: 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 nning the databa
fec0: 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 se operation. B
fed0: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 ut it.** is not
fee0: 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 safe to call thi
fef0: 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 s routine with a
ff00: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
ff10: 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 ction] that.** i
ff20: 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 s closed or migh
ff30: 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 t close before s
ff40: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
ff50: 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a () returns..**.*
ff60: 2a 20 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 * If an SQL oper
ff70: 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 ation is very ne
ff80: 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 arly finished at
ff90: 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a the time when.*
ffa0: 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 * sqlite3_interr
ffb0: 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c upt() is called,
ffc0: 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e then it might n
ffd0: 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 ot have an oppor
ffe0: 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 tunity.** to be
fff0: 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 interrupted and
10000 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 might continue t
10010 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a o completion..**
10020 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f 70 65 72 61 .** An SQL opera
10030 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 tion that is int
10040 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 errupted will re
10050 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 turn [SQLITE_INT
10060 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 49 66 20 74 ERRUPT]..** If t
10070 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 he interrupted S
10080 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 QL operation is
10090 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 an INSERT, UPDAT
100a0 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 E, or DELETE.**
100b0 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 that is inside a
100c0 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 n explicit trans
100d0 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 action, then the
100e0 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 entire transact
100f0 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 ion.** will be r
10100 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d olled back autom
10110 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 atically..**.**
10120 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 The sqlite3_inte
10130 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 rrupt(D) call is
10140 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c in effect until
10150 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 all currently r
10160 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 unning.** SQL st
10170 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 atements on [dat
10180 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
10190 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 41 ] D complete. A
101a0 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 ny new SQL state
101b0 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 ments.** that ar
101c0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 e started after
101d0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 the sqlite3_inte
101e0 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 rrupt() call and
101f0 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 before the .**
10200 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e running statemen
10210 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 ts reaches zero
10220 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 are interrupted
10230 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62 as if they had b
10240 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 een.** running p
10250 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 rior to the sqli
10260 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 te3_interrupt()
10270 63 61 6c 6c 2e 20 20 4e 65 77 20 53 51 4c 20 73 call. New SQL s
10280 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 tatements.** tha
10290 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 t are started af
102a0 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 ter the running
102b0 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 statement count
102c0 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 reaches zero are
102d0 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 .** not effected
102e0 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f by the sqlite3_
102f0 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 interrupt()..**
10300 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 A call to sqlite
10310 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 3_interrupt(D) t
10320 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 hat occurs when
10330 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e there are no run
10340 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 ning.** SQL stat
10350 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f ements is a no-o
10360 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 p and has no eff
10370 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 ect on SQL state
10380 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 ments.** that ar
10390 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 e started after
103a0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 the sqlite3_inte
103b0 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 rrupt() call ret
103c0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 urns..**.** Requ
103d0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
103e0 32 32 37 31 5d 20 5b 48 31 32 32 37 32 5d 0a 2a 2271] [H12272].*
103f0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 *.** If the data
10400 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
10410 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 closes while [sq
10420 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
10430 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 )].** is running
10440 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 then bad things
10450 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 will likely hap
10460 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 pen..*/.SQLITE_A
10470 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f PI void sqlite3_
10480 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 interrupt(sqlite
10490 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 3*);../*.** CAPI
104a0 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 3REF: Determine
104b0 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d If An SQL Statem
104c0 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 20 ent Is Complete
104d0 7b 48 31 30 35 31 30 7d 20 3c 53 37 30 32 30 30 {H10510} <S70200
104e0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f >.**.** These ro
104f0 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 utines are usefu
10500 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 l during command
10510 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 -line input to d
10520 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a etermine if the.
10530 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 ** currently ent
10540 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 ered text seems
10550 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 to form a comple
10560 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 te SQL statement
10570 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 or.** if additi
10580 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 onal input is ne
10590 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 eded before send
105a0 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 ing the text int
105b0 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 o.** SQLite for
105c0 70 61 72 73 69 6e 67 2e 20 20 54 68 65 73 65 20 parsing. These
105d0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
105e0 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 1 if the input s
105f0 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 tring.** appears
10600 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 to be a complet
10610 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e e SQL statement.
10620 20 20 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 A statement is
10630 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a judged to be.**
10640 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 complete if it
10650 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 ends with a semi
10660 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 colon token and
10670 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 is not a prefix
10680 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 of a.** well-for
10690 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47 med CREATE TRIGG
106a0 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 ER statement. S
106b0 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 emicolons that a
106c0 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 re embedded with
106d0 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 in.** string lit
106e0 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 erals or quoted
106f0 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 identifier names
10700 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 or comments are
10710 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 not.** independ
10720 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 ent tokens (they
10730 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 are part of the
10740 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 token in which
10750 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 they are.** embe
10760 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 dded) and thus d
10770 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 o not count as a
10780 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 statement termi
10790 6e 61 74 6f 72 2e 20 20 57 68 69 74 65 73 70 61 nator. Whitespa
107a0 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e ce.** and commen
107b0 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 ts that follow t
107c0 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c he final semicol
107d0 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a on are ignored..
107e0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
107f0 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 ines return 0 if
10800 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 the statement i
10810 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 49 s incomplete. I
10820 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c f a.** memory al
10830 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 location fails,
10840 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 then SQLITE_NOME
10850 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a M is returned..*
10860 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
10870 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 nes do not parse
10880 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
10890 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c nts thus.** will
108a0 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 not detect synt
108b0 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 actically incorr
108c0 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 49 ect SQL..**.** I
108d0 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 f SQLite has not
108e0 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 been initialize
108f0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 d using [sqlite3
10900 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 _initialize()] p
10910 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f rior .** to invo
10920 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d king sqlite3_com
10930 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 plete16() then s
10940 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
10950 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a e() is invoked.*
10960 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 * automatically
10970 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c by sqlite3_compl
10980 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 ete16(). If tha
10990 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e t initialization
109a0 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 fails,.** then
109b0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
109c0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f from sqlite3_co
109d0 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 mplete16() will
109e0 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 be non-zero.** r
109f0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 egardless of whe
10a00 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 ther or not the
10a10 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d input SQL is com
10a20 70 6c 65 74 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 plete..**.** Req
10a30 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 35 uirements: [H105
10a40 31 31 5d 20 5b 48 31 30 35 31 32 5d 0a 2a 2a 0a 11] [H10512].**.
10a50 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 ** The input to
10a60 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 [sqlite3_complet
10a70 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a e()] must be a z
10a80 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a ero-terminated.*
10a90 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a * UTF-8 string..
10aa0 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 **.** The input
10ab0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 to [sqlite3_comp
10ac0 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 lete16()] must b
10ad0 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 e a zero-termina
10ae0 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 ted.** UTF-16 st
10af0 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 ring in native b
10b00 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 yte order..*/.SQ
10b10 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
10b20 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f ite3_complete(co
10b30 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a nst char *sql);.
10b40 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
10b50 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 qlite3_complete1
10b60 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6(const void *sq
10b70 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 l);../*.** CAPI3
10b80 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 REF: Register A
10b90 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 Callback To Hand
10ba0 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 le SQLITE_BUSY E
10bb0 72 72 6f 72 73 20 7b 48 31 32 33 31 30 7d 20 3c rrors {H12310} <
10bc0 53 34 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S40400>.**.** Th
10bd0 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 is routine sets
10be0 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 a callback funct
10bf0 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 ion that might b
10c00 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 e invoked whenev
10c10 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 er.** an attempt
10c20 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e is made to open
10c30 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c a database tabl
10c40 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 e that another t
10c50 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 hread.** or proc
10c60 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a ess has locked..
10c70 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73 **.** If the bus
10c80 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 y callback is NU
10c90 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 LL, then [SQLITE
10ca0 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 _BUSY] or [SQLIT
10cb0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d E_IOERR_BLOCKED]
10cc0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 .** is returned
10cd0 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e immediately upon
10ce0 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 encountering th
10cf0 65 20 6c 6f 63 6b 2e 20 49 66 20 74 68 65 20 62 e lock. If the b
10d00 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 usy callback.**
10d10 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 is not NULL, the
10d20 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 n the callback w
10d30 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 ill be invoked w
10d40 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 ith two argument
10d50 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 s..**.** The fir
10d60 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 st argument to t
10d70 68 65 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 he handler is a
10d80 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 copy of the void
10d90 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a * pointer which.
10da0 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 ** is the third
10db0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
10dc0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 te3_busy_handler
10dd0 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 (). The second
10de0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 argument to.** t
10df0 68 65 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 he handler callb
10e00 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 ack is the numbe
10e10 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 r of times that
10e20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
10e30 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 has.** been inv
10e40 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f oked for this lo
10e50 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 49 66 cking event. If
10e60 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c the.** busy cal
10e70 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c lback returns 0,
10e80 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f then no additio
10e90 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 nal attempts are
10ea0 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 made to.** acce
10eb0 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ss the database
10ec0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 and [SQLITE_BUSY
10ed0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 ] or [SQLITE_IOE
10ee0 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 RR_BLOCKED] is r
10ef0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 eturned..** If t
10f00 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 he callback retu
10f10 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 rns non-zero, th
10f20 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d en another attem
10f30 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f pt.** is made to
10f40 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 open the databa
10f50 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 se for reading a
10f60 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 nd the cycle rep
10f70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 eats..**.** The
10f80 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 presence of a bu
10f90 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 sy handler does
10fa0 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 not guarantee th
10fb0 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e at it will be in
10fc0 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 voked.** when th
10fd0 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 ere is lock cont
10fe0 65 6e 74 69 6f 6e 2e 20 49 66 20 53 51 4c 69 74 ention. If SQLit
10ff0 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 e determines tha
11000 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 t invoking the b
11010 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 usy.** handler c
11020 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 ould result in a
11030 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 deadlock, it wi
11040 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 ll go ahead and
11050 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 return [SQLITE_B
11060 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 USY].** or [SQLI
11070 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 TE_IOERR_BLOCKED
11080 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 ] instead of inv
11090 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 oking the busy h
110a0 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 andler..** Consi
110b0 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 der a scenario w
110c0 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 here one process
110d0 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 is holding a re
110e0 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 ad lock that.**
110f0 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 it is trying to
11100 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 promote to a res
11110 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a erved lock and.*
11120 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 * a second proce
11130 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 ss is holding a
11140 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 reserved lock th
11150 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a at it is trying.
11160 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f ** to promote to
11170 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f an exclusive lo
11180 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 ck. The first p
11190 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 rocess cannot pr
111a0 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 oceed.** because
111b0 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 it is blocked b
111c0 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 y the second and
111d0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 the second proc
111e0 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 ess cannot.** pr
111f0 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 oceed because it
11200 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 is blocked by t
11210 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f he first. If bo
11220 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 th processes.**
11230 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 invoke the busy
11240 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 handlers, neithe
11250 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 r will make any
11260 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 progress. There
11270 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 fore,.** SQLite
11280 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
11290 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 BUSY] for the fi
112a0 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 rst process, hop
112b0 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a ing that this.**
112c0 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 will induce the
112d0 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 first process t
112e0 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 o release its re
112f0 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f ad lock and allo
11300 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 w.** the second
11310 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 process to proce
11320 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 ed..**.** The de
11330 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 fault busy callb
11340 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a ack is NULL..**.
11350 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 ** The [SQLITE_B
11360 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f USY] error is co
11370 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 nverted to [SQLI
11380 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 TE_IOERR_BLOCKED
11390 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 ].** when SQLite
113a0 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c is in the middl
113b0 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 e of a large tra
113c0 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 nsaction where a
113d0 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 ll the.** change
113e0 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 s will not fit i
113f0 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 nto the in-memor
11400 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 y cache. SQLite
11410 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 will.** already
11420 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 hold a RESERVED
11430 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 lock on the dat
11440 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 abase file, but
11450 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 it needs.** to p
11460 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b romote this lock
11470 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f to EXCLUSIVE so
11480 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 that it can spi
11490 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 ll cache.** page
114a0 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 s into the datab
114b0 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 ase file without
114c0 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 harm to concurr
114d0 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 ent.** readers.
114e0 20 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 If it is unable
114f0 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 to promote the
11500 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 lock, then the i
11510 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 n-memory.** cach
11520 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 e will be left i
11530 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e n an inconsisten
11540 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 t state and so t
11550 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 he error.** code
11560 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f is promoted fro
11570 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 m the relatively
11580 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f benign [SQLITE_
11590 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 BUSY] to.** the
115a0 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c more severe [SQL
115b0 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 ITE_IOERR_BLOCKE
115c0 44 5d 2e 20 20 54 68 69 73 20 65 72 72 6f 72 20 D]. This error
115d0 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a code promotion.*
115e0 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f * forces an auto
115f0 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f matic rollback o
11600 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 f the changes.
11610 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 See the.** <a hr
11620 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b ef="/cvstrac/wik
11630 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f i?p=CorruptionFo
11640 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 llowingBusyError
11650 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e ">.** Corruption
11660 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 FollowingBusyErr
11670 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 or</a> wiki page
11680 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f for a discussio
11690 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 n of why.** this
116a0 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a is important..*
116b0 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f *.** There can o
116c0 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 nly be a single
116d0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 busy handler def
116e0 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a ined for each.**
116f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
11700 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 ction]. Setting
11710 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 a new busy hand
11720 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a ler clears any.*
11730 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 * previously set
11740 20 68 61 6e 64 6c 65 72 2e 20 20 4e 6f 74 65 20 handler. Note
11750 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 that calling [sq
11760 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f lite3_busy_timeo
11770 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c ut()].** will al
11780 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 so set or clear
11790 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
117a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 ..**.** The busy
117b0 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 callback should
117c0 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 not take any ac
117d0 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 tions which modi
117e0 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 fy the.** databa
117f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 se connection th
11800 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 at invoked the b
11810 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e usy handler. An
11820 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a y such actions.*
11830 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 * result in unde
11840 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a fined behavior..
11850 2a 2a 20 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 ** .** Requireme
11860 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 33 31 31 5d nts:.** [H12311]
11870 20 5b 48 31 32 33 31 32 5d 20 5b 48 31 32 33 31 [H12312] [H1231
11880 34 5d 20 5b 48 31 32 33 31 36 5d 20 5b 48 31 32 4] [H12316] [H12
11890 33 31 38 5d 0a 2a 2a 0a 2a 2a 20 41 20 62 75 73 318].**.** A bus
118a0 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e y handler must n
118b0 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 ot close the dat
118c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
118d0 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 .** or [prepared
118e0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 statement] that
118f0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 invoked the bus
11900 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 y handler..*/.SQ
11910 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
11920 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 ite3_busy_handle
11930 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 r(sqlite3*, int(
11940 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 *)(void*,int), v
11950 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 oid*);../*.** CA
11960 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 PI3REF: Set A Bu
11970 73 79 20 54 69 6d 65 6f 75 74 20 7b 48 31 32 33 sy Timeout {H123
11980 34 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 40} <S40410>.**.
11990 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
119a0 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f sets a [sqlite3_
119b0 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 busy_handler | b
119c0 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 usy handler] tha
119d0 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 t sleeps.** for
119e0 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 a specified amou
119f0 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 nt of time when
11a00 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 a table is locke
11a10 64 2e 20 20 54 68 65 20 68 61 6e 64 6c 65 72 0a d. The handler.
11a20 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 ** will sleep mu
11a30 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 ltiple times unt
11a40 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 il at least "ms"
11a50 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 milliseconds of
11a60 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 sleeping.** hav
11a70 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 7b e accumulated. {
11a80 48 31 32 33 34 33 7d 20 41 66 74 65 72 20 22 6d H12343} After "m
11a90 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 s" milliseconds
11aa0 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 of sleeping,.**
11ab0 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 the handler retu
11ac0 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 rns 0 which caus
11ad0 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 es [sqlite3_step
11ae0 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a ()] to return.**
11af0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f [SQLITE_BUSY] o
11b00 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f r [SQLITE_IOERR_
11b10 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 BLOCKED]..**.**
11b20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 Calling this rou
11b30 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 tine with an arg
11b40 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 ument less than
11b50 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f or equal to zero
11b60 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c .** turns off al
11b70 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e l busy handlers.
11b80 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e .**.** There can
11b90 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c only be a singl
11ba0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 e busy handler f
11bb0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a or a particular.
11bc0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
11bd0 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 nection] any any
11be0 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 given moment.
11bf0 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 If another busy
11c00 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 handler.** was d
11c10 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b efined (using [
11c20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e sqlite3_busy_han
11c30 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 dler()]) prior t
11c40 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 o calling.** thi
11c50 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 s routine, that
11c60 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c other busy handl
11c70 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 0a 2a er is cleared..*
11c80 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
11c90 73 3a 0a 2a 2a 20 5b 48 31 32 33 34 31 5d 20 5b s:.** [H12341] [
11ca0 48 31 32 33 34 33 5d 20 5b 48 31 32 33 34 34 5d H12343] [H12344]
11cb0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
11cc0 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f nt sqlite3_busy_
11cd0 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a timeout(sqlite3*
11ce0 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a , int ms);../*.*
11cf0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 * CAPI3REF: Conv
11d00 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 enience Routines
11d10 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 For Running Que
11d20 72 69 65 73 20 7b 48 31 32 33 37 30 7d 20 3c 53 ries {H12370} <S
11d30 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 44 65 66 10000>.**.** Def
11d40 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 inition: A <b>re
11d50 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 sult table</b> i
11d60 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 s memory data st
11d70 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 ructure created
11d80 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 by the.** [sqlit
11d90 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 e3_get_table()]
11da0 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 interface. A re
11db0 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 sult table recor
11dc0 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 ds the.** comple
11dd0 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 te query results
11de0 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 from one or mor
11df0 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a e queries..**.**
11e00 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 The table conce
11e10 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 ptually has a nu
11e20 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 mber of rows and
11e30 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a columns. But.*
11e40 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 * these numbers
11e50 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 are not part of
11e60 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 the result table
11e70 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a itself. These.
11e80 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f ** numbers are o
11e90 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 btained separate
11ea0 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 ly. Let N be th
11eb0 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 e number of rows
11ec0 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 .** and M be the
11ed0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
11ee0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 ns..**.** A resu
11ef0 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 lt table is an a
11f00 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 rray of pointers
11f10 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 to zero-termina
11f20 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 ted UTF-8 string
11f30 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 s..** There are
11f40 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 (N+1)*M elements
11f50 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 in the array.
11f60 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e The first M poin
11f70 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f ters point.** to
11f80 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
11f90 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 strings that c
11fa0 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 ontain the names
11fb0 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e of the columns.
11fc0 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e .** The remainin
11fd0 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f g entries all po
11fe0 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 int to query res
11ff0 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 ults. NULL valu
12000 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 es result.** in
12010 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 NULL pointers.
12020 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 All other values
12030 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 are in their UT
12040 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 F-8 zero-termina
12050 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 ted.** string re
12060 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 presentation as
12070 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c returned by [sql
12080 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
12090 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 ()]..**.** A res
120a0 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 ult table might
120b0 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f consist of one o
120c0 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c r more memory al
120d0 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 locations..** It
120e0 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 is not safe to
120f0 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 pass a result ta
12100 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 ble directly to
12110 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
12120 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 ..** A result ta
12130 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 ble should be de
12140 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 allocated using
12150 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 [sqlite3_free_ta
12160 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 ble()]..**.** As
12170 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 an example of t
12180 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 he result table
12190 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 format, suppose
121a0 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a a query result.*
121b0 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a * is as follows:
121c0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
121d0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 te><pre>.**
121e0 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c Name |
121f0 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d Age.** -
12200 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
12210 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 ------.**
12220 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 Alice | 4
12230 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 3.** Bob
12240 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 | 28.**
12250 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 Cindy
12260 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 | 21.** </pre
12270 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
12280 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 *.** There are t
12290 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 wo column (M==2)
122a0 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 and three rows
122b0 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 (N==3). Thus th
122c0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c e.** result tabl
122d0 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e e has 8 entries.
122e0 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 Suppose the re
122f0 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 sult table is st
12300 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 ored.** in an ar
12310 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 ray names azResu
12320 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 lt. Then azResu
12330 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f lt holds this co
12340 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c ntent:.**.** <bl
12350 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
12360 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
12370 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 t[0] = "Name
12380 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
12390 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 esult[1] = "
123a0 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 Age";.**
123b0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 azResult[2]
123c0 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 = "Alice";.**
123d0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
123e0 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 1;3] = "43";.**
123f0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
12400 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a #91;4] = "Bob";.
12410 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
12420 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 lt[5] = "28"
12430 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 ;.** azRe
12440 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 sult[6] = "C
12450 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 indy";.**
12460 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d azResult[7]
12470 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 = "21";.** </pr
12480 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a e></blockquote>.
12490 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
124a0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 3_get_table() fu
124b0 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 nction evaluates
124c0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 one or more.**
124d0 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 semicolon-separa
124e0 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ted SQL statemen
124f0 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 ts in the zero-t
12500 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a erminated UTF-8.
12510 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 ** string of its
12520 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 2nd parameter.
12530 20 49 74 20 72 65 74 75 72 6e 73 20 61 20 72 65 It returns a re
12540 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 sult table to th
12550 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 e.** pointer giv
12560 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 en in its 3rd pa
12570 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 rameter..**.** A
12580 66 74 65 72 20 74 68 65 20 63 61 6c 6c 69 6e 67 fter the calling
12590 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20 66 69 function has fi
125a0 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 65 nished using the
125b0 20 72 65 73 75 6c 74 2c 20 69 74 20 73 68 6f 75 result, it shou
125c0 6c 64 0a 2a 2a 20 70 61 73 73 20 74 68 65 20 70 ld.** pass the p
125d0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 72 65 ointer to the re
125e0 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 73 71 sult table to sq
125f0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 lite3_free_table
12600 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a () in order to.*
12610 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 * release the me
12620 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 mory that was ma
12630 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 lloced. Because
12640 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a of the way the.
12650 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c ** [sqlite3_mall
12660 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 oc()] happens wi
12670 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 thin sqlite3_get
12680 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 _table(), the ca
12690 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f lling.** functio
126a0 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 n must not try t
126b0 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f o call [sqlite3_
126c0 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 free()] directly
126d0 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 . Only.** [sqli
126e0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 te3_free_table()
126f0 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c ] is able to rel
12700 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 ease the memory
12710 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 properly and saf
12720 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ely..**.** The s
12730 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 qlite3_get_table
12740 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 () interface is
12750 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 implemented as a
12760 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a wrapper around.
12770 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 ** [sqlite3_exec
12780 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 ()]. The sqlite
12790 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 3_get_table() ro
127a0 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 utine does not h
127b0 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f ave access.** to
127c0 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 any internal da
127d0 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 ta structures of
127e0 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 SQLite. It use
127f0 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 s only the publi
12800 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 c.** interface d
12810 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 efined here. As
12820 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 a consequence,
12830 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 errors that occu
12840 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 r in the.** wrap
12850 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 per layer outsid
12860 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 e of the interna
12870 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 l [sqlite3_exec(
12880 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a )] call are not.
12890 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 ** reflected in
128a0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 subsequent calls
128b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 to [sqlite3_err
128c0 63 6f 64 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 code()] or [sqli
128d0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a te3_errmsg()]..*
128e0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
128f0 73 3a 0a 2a 2a 20 5b 48 31 32 33 37 31 5d 20 5b s:.** [H12371] [
12900 48 31 32 33 37 33 5d 20 5b 48 31 32 33 37 34 5d H12373] [H12374]
12910 20 5b 48 31 32 33 37 36 5d 20 5b 48 31 32 33 37 [H12376] [H1237
12920 39 5d 20 5b 48 31 32 33 38 32 5d 0a 2a 2f 0a 53 9] [H12382].*/.S
12930 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
12940 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
12950 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
12960 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f /* An o
12970 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a pen database */.
12980 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 const char *zS
12990 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 ql, /* SQL t
129a0 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a o be evaluated *
129b0 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 /. char ***pazR
129c0 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 esult, /* Res
129d0 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 ults of the quer
129e0 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f y */. int *pnRo
129f0 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 w, /*
12a00 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 Number of result
12a10 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 rows written he
12a20 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 re */. int *pnC
12a30 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a olumn, /*
12a40 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c Number of resul
12a50 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 t columns writte
12a60 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 n here */. char
12a70 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 **pzErrmsg
12a80 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 /* Error msg w
12a90 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 ritten here */.)
12aa0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 ;.SQLITE_API voi
12ab0 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 d sqlite3_free_t
12ac0 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 able(char **resu
12ad0 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 lt);../*.** CAPI
12ae0 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 3REF: Formatted
12af0 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 String Printing
12b00 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 37 34 30 Functions {H1740
12b10 30 7d 20 3c 53 37 30 30 30 30 3e 3c 53 32 30 30 0} <S70000><S200
12b20 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 00>.**.** These
12b30 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 routines are wor
12b40 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 k-alikes of the
12b50 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c "printf()" famil
12b60 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a y of functions.*
12b70 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 * from the stand
12b80 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a ard C library..*
12b90 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
12ba0 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 _mprintf() and s
12bb0 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 qlite3_vmprintf(
12bc0 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 ) routines write
12bd0 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 their.** result
12be0 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 s into memory ob
12bf0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c tained from [sql
12c00 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a ite3_malloc()]..
12c10 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 ** The strings r
12c20 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 eturned by these
12c30 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 two routines sh
12c40 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 ould be.** relea
12c50 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f sed by [sqlite3_
12c60 66 72 65 65 28 29 5d 2e 20 20 42 6f 74 68 20 72 free()]. Both r
12c70 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 outines return a
12c80 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 .** NULL pointer
12c90 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c if [sqlite3_mal
12ca0 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 loc()] is unable
12cb0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f to allocate eno
12cc0 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f ugh.** memory to
12cd0 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 hold the result
12ce0 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a ing string..**.*
12cf0 2a 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 * In sqlite3_snp
12d00 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 rintf() routine
12d10 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 is similar to "s
12d20 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a nprintf()" from.
12d30 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 ** the standard
12d40 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 C library. The
12d50 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 result is writte
12d60 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 n into the.** bu
12d70 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 ffer supplied as
12d80 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 the second para
12d90 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 meter whose size
12da0 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 is given by.**
12db0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 the first parame
12dc0 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 ter. Note that t
12dd0 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a he order of the.
12de0 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 ** first two par
12df0 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72 ameters is rever
12e00 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 sed from snprint
12e10 66 28 29 2e 20 20 54 68 69 73 20 69 73 20 61 6e f(). This is an
12e20 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 .** historical a
12e30 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e ccident that can
12e40 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 not be fixed wit
12e50 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a hout breaking.**
12e60 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 backwards compa
12e70 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65 20 tibility. Note
12e80 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 also that sqlite
12e90 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 3_snprintf().**
12ea0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
12eb0 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 r to its buffer
12ec0 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e instead of the n
12ed0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 umber of.** char
12ee0 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 acters actually
12ef0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 written into the
12f00 20 62 75 66 66 65 72 2e 20 20 57 65 20 61 64 6d buffer. We adm
12f10 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e it that.** the n
12f20 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 umber of charact
12f30 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c ers written woul
12f40 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 d be a more usef
12f50 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c ul return.** val
12f60 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 ue but we cannot
12f70 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c change the impl
12f80 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 ementation of sq
12f90 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 lite3_snprintf()
12fa0 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 .** now without
12fb0 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 breaking compati
12fc0 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 bility..**.** As
12fd0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 long as the buf
12fe0 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 fer size is grea
12ff0 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 ter than zero, s
13000 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
13010 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 ).** guarantees
13020 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 that the buffer
13030 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 is always zero-t
13040 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20 erminated. The
13050 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 first.** paramet
13060 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f er "n" is the to
13070 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 tal size of the
13080 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e buffer, includin
13090 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 g space for.** t
130a0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 he zero terminat
130b0 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 or. So the long
130c0 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 est string that
130d0 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c can be completel
130e0 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c y.** written wil
130f0 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 l be n-1 charact
13100 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ers..**.** These
13110 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d routines all im
13120 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 plement some add
13130 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 itional formatti
13140 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 ng.** options th
13150 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f at are useful fo
13160 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 r constructing S
13170 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a QL statements..*
13180 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 * All of the usu
13190 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d al printf() form
131a0 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 atting options a
131b0 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 pply. In additi
131c0 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 on, there.** is
131d0 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 are "%q", "%Q",
131e0 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 and "%z" options
131f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f ..**.** The %q o
13200 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 ption works like
13210 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 %s in that it s
13220 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c ubstitutes a nul
13230 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 l-terminated.**
13240 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 string from the
13250 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 argument list.
13260 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 But %q also doub
13270 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 les every '\'' c
13280 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 haracter..** %q
13290 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 is designed for
132a0 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 use inside a str
132b0 69 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 79 ing literal. By
132c0 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 doubling each '
132d0 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 \''.** character
132e0 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 it escapes that
132f0 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 character and a
13300 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 llows it to be i
13310 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 nserted into.**
13320 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a the string..**.*
13330 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 * For example, a
13340 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 ssume the string
13350 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 variable zText
13360 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 contains text as
13370 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 follows:.**.**
13380 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
13390 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 >.** char *zTex
133a0 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 t = "It's a happ
133b0 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 y day!";.** </pr
133c0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a e></blockquote>.
133d0 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 **.** One can us
133e0 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 e this text in a
133f0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 n SQL statement
13400 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a as follows:.**.*
13410 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
13420 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 re>.** char *zS
13430 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 QL = sqlite3_mpr
13440 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 intf("INSERT INT
13450 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 O table VALUES('
13460 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a %q')", zText);.*
13470 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 * sqlite3_exec(
13480 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 db, zSQL, 0, 0,
13490 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 0);.** sqlite3_
134a0 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c free(zSQL);.** <
134b0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
134c0 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 e>.**.** Because
134d0 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 the %q format s
134e0 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 tring is used, t
134f0 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 he '\'' characte
13500 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 r in zText.** is
13510 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 escaped and the
13520 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 SQL generated i
13530 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a s as follows:.**
13540 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
13550 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 <pre>.** INSERT
13560 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c INTO table1 VAL
13570 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 UES('It''s a hap
13580 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 py day!').** </p
13590 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
135a0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 .**.** This is c
135b0 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 orrect. Had we
135c0 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 used %s instead
135d0 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 of %q, the gener
135e0 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c ated SQL.** woul
135f0 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 d have looked li
13600 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c ke this:.**.** <
13610 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
13620 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f .** INSERT INTO
13630 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 table1 VALUES('
13640 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 It's a happy day
13650 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f !');.** </pre></
13660 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
13670 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 * This second ex
13680 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 ample is an SQL
13690 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 syntax error. A
136a0 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 s a general rule
136b0 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 you should.** a
136c0 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 lways use %q ins
136d0 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 tead of %s when
136e0 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 inserting text i
136f0 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 nto a string lit
13700 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 eral..**.** The
13710 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 %Q option works
13720 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 like %q except i
13730 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 t also adds sing
13740 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 le quotes around
13750 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 .** the outside
13760 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 of the total str
13770 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c ing. Additional
13780 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d ly, if the param
13790 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 eter in the.** a
137a0 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 rgument list is
137b0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 a NULL pointer,
137c0 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 %Q substitutes t
137d0 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 he text "NULL" (
137e0 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c without.** singl
137f0 65 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c 61 e quotes) in pla
13800 63 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70 74 ce of the %Q opt
13810 69 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65 78 ion. So, for ex
13820 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 ample, one could
13830 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f say:.**.** <blo
13840 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a ckquote><pre>.**
13850 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 char *zSQL = s
13860 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 qlite3_mprintf("
13870 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c INSERT INTO tabl
13880 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a e VALUES(%Q)", z
13890 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 Text);.** sqlit
138a0 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c e3_exec(db, zSQL
138b0 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 , 0, 0, 0);.**
138c0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 sqlite3_free(zSQ
138d0 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 L);.** </pre></b
138e0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
138f0 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 The code above
13900 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f will render a co
13910 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d rrect SQL statem
13920 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a ent in the zSQL.
13930 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e ** variable even
13940 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 if the zText va
13950 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c riable is a NULL
13960 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 pointer..**.**
13970 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 The "%z" formatt
13980 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 ing option works
13990 20 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 25 exactly like "%
139a0 73 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 s" with the.** a
139b0 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 ddition that aft
139c0 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 er the string ha
139d0 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 s been read and
139e0 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 copied into.** t
139f0 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 he result, [sqli
13a00 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 te3_free()] is c
13a10 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 alled on the inp
13a20 75 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44 7d ut string. {END}
13a30 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
13a40 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 34 30 33 5d nts:.** [H17403]
13a50 20 5b 48 31 37 34 30 36 5d 20 5b 48 31 37 34 30 [H17406] [H1740
13a60 37 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 7].*/.SQLITE_API
13a70 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d char *sqlite3_m
13a80 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 printf(const cha
13a90 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f r*,...);.SQLITE_
13aa0 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 API char *sqlite
13ab0 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 3_vmprintf(const
13ac0 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 char*, va_list)
13ad0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 ;.SQLITE_API cha
13ae0 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 r *sqlite3_snpri
13af0 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f ntf(int,char*,co
13b00 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b nst char*, ...);
13b10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
13b20 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 : Memory Allocat
13b30 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 20 7b 48 ion Subsystem {H
13b40 31 37 33 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 17300} <S20000>.
13b50 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 **.** The SQLite
13b60 20 63 6f 72 65 20 20 75 73 65 73 20 74 68 65 73 core uses thes
13b70 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 e three routines
13b80 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 for all of its
13b90 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 own.** internal
13ba0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
13bb0 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 n needs. "Core"
13bc0 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 in the previous
13bd0 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 sentence.** does
13be0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 not include ope
13bf0 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 rating-system sp
13c00 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 ecific VFS imple
13c10 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a mentation. The.
13c20 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 ** Windows VFS u
13c30 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f ses native mallo
13c40 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 c() and free() f
13c50 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f or some operatio
13c60 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ns..**.** The sq
13c70 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 lite3_malloc() r
13c80 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 outine returns a
13c90 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c pointer to a bl
13ca0 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 ock.** of memory
13cb0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 at least N byte
13cc0 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 s in length, whe
13cd0 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 re N is the para
13ce0 6d 65 74 65 72 2e 0a 2a 2a 20 49 66 20 73 71 6c meter..** If sql
13cf0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 ite3_malloc() is
13d00 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 unable to obtai
13d10 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 n sufficient fre
13d20 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 e.** memory, it
13d30 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 returns a NULL p
13d40 6f 69 6e 74 65 72 2e 20 20 49 66 20 74 68 65 20 ointer. If the
13d50 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a parameter N to.*
13d60 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 * sqlite3_malloc
13d70 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 () is zero or ne
13d80 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 gative then sqli
13d90 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 te3_malloc() ret
13da0 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 urns.** a NULL p
13db0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 ointer..**.** Ca
13dc0 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 lling sqlite3_fr
13dd0 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e ee() with a poin
13de0 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 ter previously r
13df0 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 eturned.** by sq
13e00 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f lite3_malloc() o
13e10 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f r sqlite3_reallo
13e20 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 c() releases tha
13e30 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 t memory so.** t
13e40 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 hat it might be
13e50 72 65 75 73 65 64 2e 20 20 54 68 65 20 73 71 6c reused. The sql
13e60 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 ite3_free() rout
13e70 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f ine is.** a no-o
13e80 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 p if is called w
13e90 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 ith a NULL point
13ea0 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e er. Passing a N
13eb0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 ULL pointer.** t
13ec0 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 o sqlite3_free()
13ed0 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 is harmless. A
13ee0 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 fter being freed
13ef0 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 , memory.** shou
13f00 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 ld neither be re
13f10 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 ad nor written.
13f20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 Even reading pr
13f30 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a eviously freed.*
13f40 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 * memory might r
13f50 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 esult in a segme
13f60 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 ntation fault or
13f70 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 other severe er
13f80 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 ror..** Memory c
13f90 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 orruption, a seg
13fa0 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c mentation fault,
13fb0 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 or other severe
13fc0 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 error.** might
13fd0 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 result if sqlite
13fe0 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 3_free() is call
13ff0 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 ed with a non-NU
14000 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a LL pointer that.
14010 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 ** was not obtai
14020 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 ned from sqlite3
14030 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c _malloc() or sql
14040 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a ite3_realloc()..
14050 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
14060 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 3_realloc() inte
14070 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 rface attempts t
14080 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 o resize a.** pr
14090 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ior memory alloc
140a0 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c ation to be at l
140b0 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 east N bytes, wh
140c0 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 ere N is the.**
140d0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
140e0 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c . The memory al
140f0 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 location to be r
14100 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 esized is the fi
14110 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 rst.** parameter
14120 2e 20 20 49 66 20 74 68 65 20 66 69 72 73 74 20 . If the first
14130 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
14140 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a ite3_realloc().*
14150 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e * is a NULL poin
14160 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 ter then its beh
14170 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 avior is identic
14180 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a al to calling.**
14190 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
141a0 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 N) where N is th
141b0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
141c0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 er to sqlite3_re
141d0 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 49 66 20 74 alloc()..** If t
141e0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
141f0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 ter to sqlite3_r
14200 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f ealloc() is zero
14210 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 or.** negative
14220 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f then the behavio
14230 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 r is exactly the
14240 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 same as calling
14250 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 .** sqlite3_free
14260 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74 (P) where P is t
14270 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
14280 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 er to sqlite3_re
14290 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 73 71 6c 69 alloc()..** sqli
142a0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 te3_realloc() re
142b0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
142c0 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f to a memory allo
142d0 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 cation.** of at
142e0 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e least N bytes in
142f0 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 size or NULL if
14300 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f sufficient memo
14310 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c ry is unavailabl
14320 65 2e 0a 2a 2a 20 49 66 20 4d 20 69 73 20 74 68 e..** If M is th
14330 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 e size of the pr
14340 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 ior allocation,
14350 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 then min(N,M) by
14360 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 tes.** of the pr
14370 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 ior allocation a
14380 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 re copied into t
14390 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 he beginning of
143a0 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a buffer returned.
143b0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 ** by sqlite3_re
143c0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 alloc() and the
143d0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e prior allocation
143e0 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 is freed..** If
143f0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
14400 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c () returns NULL,
14410 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 then the prior
14420 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 allocation.** is
14430 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a not freed..**.*
14440 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 * The memory ret
14450 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
14460 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 _malloc() and sq
14470 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a lite3_realloc().
14480 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 ** is always ali
14490 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 gned to at least
144a0 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 an 8 byte bound
144b0 61 72 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a ary. {END}.**.**
144c0 20 54 68 65 20 64 65 66 61 75 6c 74 20 69 6d 70 The default imp
144d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 lementation of t
144e0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
144f0 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 75 tion subsystem u
14500 73 65 73 0a 2a 2a 20 74 68 65 20 6d 61 6c 6c 6f ses.** the mallo
14510 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 c(), realloc() a
14520 6e 64 20 66 72 65 65 28 29 20 70 72 6f 76 69 64 nd free() provid
14530 65 64 20 62 79 20 74 68 65 20 73 74 61 6e 64 61 ed by the standa
14540 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a rd C library..**
14550 20 7b 48 31 37 33 38 32 7d 20 48 6f 77 65 76 65 {H17382} Howeve
14560 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 r, if SQLite is
14570 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 compiled with th
14580 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 45 4d 4f e.** SQLITE_MEMO
14590 52 59 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f RY_SIZE=<i>NNN</
145a0 69 3e 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f i> C preprocesso
145b0 72 20 6d 61 63 72 6f 20 28 77 68 65 72 65 20 3c r macro (where <
145c0 69 3e 4e 4e 4e 3c 2f 69 3e 0a 2a 2a 20 69 73 20 i>NNN</i>.** is
145d0 61 6e 20 69 6e 74 65 67 65 72 29 2c 20 74 68 65 an integer), the
145e0 6e 20 53 51 4c 69 74 65 20 63 72 65 61 74 65 20 n SQLite create
145f0 61 20 73 74 61 74 69 63 20 61 72 72 61 79 20 6f a static array o
14600 66 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 3c 69 f at least.** <i
14610 3e 4e 4e 4e 3c 2f 69 3e 20 62 79 74 65 73 20 69 >NNN</i> bytes i
14620 6e 20 73 69 7a 65 20 61 6e 64 20 75 73 65 73 20 n size and uses
14630 74 68 61 74 20 61 72 72 61 79 20 66 6f 72 20 61 that array for a
14640 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 ll of its dynami
14650 63 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f c.** memory allo
14660 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 7b 45 cation needs. {E
14670 4e 44 7d 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 ND} Additional
14680 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
14690 20 6f 70 74 69 6f 6e 73 0a 2a 2a 20 6d 61 79 20 options.** may
146a0 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 be added in futu
146b0 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a re releases..**.
146c0 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 ** In SQLite ver
146d0 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 sion 3.5.0 and 3
146e0 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 .5.1, it was pos
146f0 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a sible to define.
14700 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d ** the SQLITE_OM
14710 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 IT_MEMORY_ALLOCA
14720 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 TION which would
14730 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 cause the built
14740 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 -in.** implement
14750 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 ation of these r
14760 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d outines to be om
14770 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 itted. That cap
14780 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f ability.** is no
14790 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 longer provided
147a0 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e . Only built-in
147b0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
147c0 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a rs can be used..
147d0 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 **.** The Window
147e0 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c s OS interface l
147f0 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 ayer calls.** th
14800 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 e system malloc(
14810 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 ) and free() dir
14820 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 ectly when conve
14830 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d rting.** filenam
14840 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 es between the U
14850 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 TF-8 encoding us
14860 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 ed by SQLite.**
14870 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c and whatever fil
14880 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 ename encoding i
14890 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 s used by the pa
148a0 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 rticular Windows
148b0 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e .** installation
148c0 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 . Memory alloca
148d0 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20 tion errors are
148e0 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a detected, but.**
148f0 20 74 68 65 79 20 61 72 65 20 72 65 70 6f 72 74 they are report
14900 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 ed back as [SQLI
14910 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a TE_CANTOPEN] or.
14920 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 ** [SQLITE_IOERR
14930 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 ] rather than [S
14940 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a QLITE_NOMEM]..**
14950 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
14960 3a 0a 2a 2a 20 5b 48 31 37 33 30 33 5d 20 5b 48 :.** [H17303] [H
14970 31 37 33 30 34 5d 20 5b 48 31 37 33 30 35 5d 20 17304] [H17305]
14980 5b 48 31 37 33 30 36 5d 20 5b 48 31 37 33 31 30 [H17306] [H17310
14990 5d 20 5b 48 31 37 33 31 32 5d 20 5b 48 31 37 33 ] [H17312] [H173
149a0 31 35 5d 20 5b 48 31 37 33 31 38 5d 0a 2a 2a 20 15] [H17318].**
149b0 5b 48 31 37 33 32 31 5d 20 5b 48 31 37 33 32 32 [H17321] [H17322
149c0 5d 20 5b 48 31 37 33 32 33 5d 0a 2a 2a 0a 2a 2a ] [H17323].**.**
149d0 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 The pointer arg
149e0 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 uments to [sqlit
149f0 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b e3_free()] and [
14a00 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
14a10 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 )].** must be ei
14a20 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 ther NULL or els
14a30 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 e pointers obtai
14a40 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 ned from a prior
14a50 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f .** invocation o
14a60 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f f [sqlite3_mallo
14a70 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 c()] or [sqlite3
14a80 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 _realloc()] that
14a90 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 have.** not yet
14aa0 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a been released..
14ab0 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 **.** The applic
14ac0 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 ation must not r
14ad0 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 ead or write any
14ae0 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c part of.** a bl
14af0 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 ock of memory af
14b00 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 ter it has been
14b10 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a released using.*
14b20 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 * [sqlite3_free(
14b30 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 )] or [sqlite3_r
14b40 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 ealloc()]..*/.SQ
14b50 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 LITE_API void *s
14b60 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e qlite3_malloc(in
14b70 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 t);.SQLITE_API v
14b80 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 oid *sqlite3_rea
14b90 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 lloc(void*, int)
14ba0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 ;.SQLITE_API voi
14bb0 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 d sqlite3_free(v
14bc0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 oid*);../*.** CA
14bd0 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 PI3REF: Memory A
14be0 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 llocator Statist
14bf0 69 63 73 20 7b 48 31 37 33 37 30 7d 20 3c 53 33 ics {H17370} <S3
14c00 30 32 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 0210>.**.** SQLi
14c10 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 te provides thes
14c20 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 e two interfaces
14c30 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f for reporting o
14c40 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 n the status.**
14c50 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
14c60 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 malloc()], [sqli
14c70 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 te3_free()], and
14c80 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f [sqlite3_reallo
14c90 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 c()].** routines
14ca0 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 , which form the
14cb0 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 built-in memory
14cc0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 allocation subs
14cd0 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 ystem..**.** Req
14ce0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
14cf0 31 37 33 37 31 5d 20 5b 48 31 37 33 37 33 5d 20 17371] [H17373]
14d00 5b 48 31 37 33 37 34 5d 20 5b 48 31 37 33 37 35 [H17374] [H17375
14d10 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
14d20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 sqlite3_int64 sq
14d30 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 lite3_memory_use
14d40 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f d(void);.SQLITE_
14d50 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 API sqlite3_int6
14d60 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 4 sqlite3_memory
14d70 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 _highwater(int r
14d80 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a esetFlag);../*.*
14d90 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 * CAPI3REF: Pseu
14da0 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 do-Random Number
14db0 20 47 65 6e 65 72 61 74 6f 72 20 7b 48 31 37 33 Generator {H173
14dc0 39 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 90} <S20000>.**.
14dd0 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 ** SQLite contai
14de0 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 ns a high-qualit
14df0 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 y pseudo-random
14e00 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 number generator
14e10 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a (PRNG) used to.
14e20 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d ** select random
14e30 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 [ROWID | ROWIDs
14e40 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 ] when inserting
14e50 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 new records int
14e60 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a o a table that.*
14e70 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 * already uses t
14e80 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 he largest possi
14e90 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 ble [ROWID]. Th
14ea0 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 e PRNG is also u
14eb0 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 sed for.** the b
14ec0 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 uild-in random()
14ed0 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 and randomblob(
14ee0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e ) SQL functions.
14ef0 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 This interface
14f00 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 allows.** appli
14f10 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 cations to acces
14f20 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 s the same PRNG
14f30 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 for other purpos
14f40 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c es..**.** A call
14f50 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 to this routine
14f60 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 stores N bytes
14f70 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e of randomness in
14f80 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a to buffer P..**.
14f90 2a 2a 20 54 68 65 20 66 69 72 73 74 20 74 69 6d ** The first tim
14fa0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 e this routine i
14fb0 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 s invoked (eithe
14fc0 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 r internally or
14fd0 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 by.** the applic
14fe0 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 ation) the PRNG
14ff0 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 is seeded using
15000 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 randomness obtai
15010 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 ned.** from the
15020 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 xRandomness meth
15030 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c od of the defaul
15040 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 t [sqlite3_vfs]
15050 6f 62 6a 65 63 74 2e 0a 2a 2a 20 4f 6e 20 61 6c object..** On al
15060 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 l subsequent inv
15070 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 ocations, the ps
15080 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 eudo-randomness
15090 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 is generated.**
150a0 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 internally and w
150b0 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 ithout recourse
150c0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
150d0 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 vfs] xRandomness
150e0 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a .** method..**.*
150f0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
15100 2a 2a 20 5b 48 31 37 33 39 32 5d 0a 2a 2f 0a 53 ** [H17392].*/.S
15110 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
15120 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 qlite3_randomnes
15130 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 s(int N, void *P
15140 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
15150 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 EF: Compile-Time
15160 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 Authorization C
15170 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 35 30 30 allbacks {H12500
15180 7d 20 3c 53 37 30 31 30 30 3e 0a 2a 2a 0a 2a 2a } <S70100>.**.**
15190 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 This routine re
151a0 67 69 73 74 65 72 73 20 61 20 61 75 74 68 6f 72 gisters a author
151b0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 izer callback wi
151c0 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a th a particular.
151d0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
151e0 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 nection], suppli
151f0 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 ed in the first
15200 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 argument..** The
15210 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
15220 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
15230 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 as SQL statement
15240 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 s are being comp
15250 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 iled.** by [sqli
15260 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f te3_prepare()] o
15270 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b r its variants [
15280 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
15290 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 v2()],.** [sqlit
152a0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 e3_prepare16()]
152b0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 and [sqlite3_pre
152c0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 41 pare16_v2()]. A
152d0 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 t various.** poi
152e0 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 nts during the c
152f0 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 ompilation proce
15300 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 ss, as logic is
15310 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a being created.**
15320 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 to perform vari
15330 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 ous actions, the
15340 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
15350 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
15360 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f to.** see if tho
15370 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 se actions are a
15380 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20 61 75 74 llowed. The aut
15390 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
153a0 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 should.** retur
153b0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f n [SQLITE_OK] to
153c0 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f allow the actio
153d0 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 n, [SQLITE_IGNOR
153e0 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 E] to disallow t
153f0 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 he.** specific a
15400 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 ction but allow
15410 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
15420 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f t to continue to
15430 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c be.** compiled,
15440 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 or [SQLITE_DENY
15450 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 ] to cause the e
15460 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d ntire SQL statem
15470 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a ent to be.** rej
15480 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 ected with an er
15490 72 6f 72 2e 20 20 49 66 20 74 68 65 20 61 75 74 ror. If the aut
154a0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
154b0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 returns.** any
154c0 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e value other than
154d0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d [SQLITE_IGNORE]
154e0 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f , [SQLITE_OK], o
154f0 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a r [SQLITE_DENY].
15500 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c ** then the [sql
15510 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
15520 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 )] or equivalent
15530 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 call that trigg
15540 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 ered.** the auth
15550 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c orizer will fail
15560 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d with an error m
15570 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 essage..**.** Wh
15580 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 en the callback
15590 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
155a0 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 OK], that means
155b0 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a the operation.**
155c0 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b requested is ok
155d0 2e 20 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c . When the call
155e0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 back returns [SQ
155f0 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a LITE_DENY], the.
15600 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
15610 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 are_v2()] or equ
15620 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 ivalent call tha
15630 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a t triggered the.
15640 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 ** authorizer wi
15650 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 ll fail with an
15660 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 error message ex
15670 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a plaining that.**
15680 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 access is denie
15690 64 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 d. .**.** The fi
156a0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f rst parameter to
156b0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
156c0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f callback is a co
156d0 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a py of the third.
156e0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 ** parameter to
156f0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f the sqlite3_set_
15700 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 authorizer() int
15710 65 72 66 61 63 65 2e 20 54 68 65 20 73 65 63 6f erface. The seco
15720 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 nd parameter.**
15730 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 to the callback
15740 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 is an integer [S
15750 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 QLITE_COPY | act
15760 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 ion code] that s
15770 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 pecifies.** the
15780 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f particular actio
15790 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a n to be authoriz
157a0 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 74 68 ed. The third th
157b0 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 rough sixth para
157c0 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 meters.** to the
157d0 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 callback are ze
157e0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 ro-terminated st
157f0 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 rings that conta
15800 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a in additional.**
15810 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 details about t
15820 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 he action to be
15830 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a authorized..**.*
15840 2a 20 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 * If the action
15850 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f code is [SQLITE_
15860 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 READ].** and the
15870 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
15880 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 s [SQLITE_IGNORE
15890 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 ] then the.** [p
158a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
158b0 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 t] statement is
158c0 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 constructed to s
158d0 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e ubstitute.** a N
158e0 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 ULL value in pla
158f0 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 ce of the table
15900 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c column that woul
15910 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 d have.** been r
15920 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f ead if [SQLITE_O
15930 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 K] had been retu
15940 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 rned. The [SQLI
15950 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 TE_IGNORE].** re
15960 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 turn can be used
15970 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 to deny an untr
15980 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73 usted user acces
15990 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a s to individual.
159a0 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 ** columns of a
159b0 74 61 62 6c 65 2e 0a 2a 2a 20 49 66 20 74 68 65 table..** If the
159c0 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 action code is
159d0 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 [SQLITE_DELETE]
159e0 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b and the callback
159f0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c returns.** [SQL
15a00 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e ITE_IGNORE] then
15a10 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 the [DELETE] op
15a20 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 eration proceeds
15a30 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 but the.** [tru
15a40 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 ncate optimizati
15a50 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 on] is disabled
15a60 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 and all rows are
15a70 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 deleted individ
15a80 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 ually..**.** An
15a90 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 authorizer is us
15aa0 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 ed when [sqlite3
15ab0 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 _prepare | prepa
15ac0 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 ring].** SQL sta
15ad0 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 tements from an
15ae0 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 untrusted source
15af0 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 , to ensure that
15b00 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
15b10 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 nts.** do not tr
15b20 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 y to access data
15b30 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c they are not al
15b40 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 lowed to see, or
15b50 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f that they do no
15b60 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 t.** try to exec
15b70 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 ute malicious st
15b80 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 atements that da
15b90 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 mage the databas
15ba0 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 e. For.** examp
15bb0 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 le, an applicati
15bc0 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 on may allow a u
15bd0 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 ser to enter arb
15be0 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 itrary.** SQL qu
15bf0 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 eries for evalua
15c00 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 tion by a databa
15c10 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 se. But the app
15c20 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a lication does.**
15c30 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 not want the us
15c40 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f er to be able to
15c50 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 make arbitrary
15c60 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a changes to the.*
15c70 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 * database. An
15c80 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 authorizer could
15c90 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 then be put in
15ca0 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a place while the.
15cb0 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 ** user-entered
15cc0 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 SQL is being [sq
15cd0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 lite3_prepare |
15ce0 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a prepared] that.*
15cf0 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 * disallows ever
15d00 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 ything except [S
15d10 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 ELECT] statement
15d20 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 s..**.** Applica
15d30 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 tions that need
15d40 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 to process SQL f
15d50 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f rom untrusted so
15d60 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 urces.** might a
15d70 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 lso consider low
15d80 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c ering resource l
15d90 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c imits using [sql
15da0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a ite3_limit()].**
15db0 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 and limiting da
15dc0 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e tabase size usin
15dd0 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f g the [max_page_
15de0 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a count] [PRAGMA].
15df0 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 ** in addition t
15e00 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f o using an autho
15e10 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c rizer..**.** Onl
15e20 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f y a single autho
15e30 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 rizer can be in
15e40 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 place on a datab
15e50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase connection.*
15e60 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 * at a time. Ea
15e70 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 ch call to sqlit
15e80 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
15e90 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a r overrides the.
15ea0 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c ** previous call
15eb0 2e 20 20 44 69 73 61 62 6c 65 20 74 68 65 20 61 . Disable the a
15ec0 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 uthorizer by ins
15ed0 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 talling a NULL c
15ee0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 allback..** The
15ef0 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 authorizer is di
15f00 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c sabled by defaul
15f10 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 t..**.** The aut
15f20 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
15f30 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 must not do any
15f40 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 thing that will
15f50 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 modify.** the da
15f60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
15f70 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 n that invoked t
15f80 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
15f90 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 llback..** Note
15fa0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 that [sqlite3_pr
15fb0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 epare_v2()] and
15fc0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
15fd0 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 both modify the
15fe0 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 ir.** database c
15ff0 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 onnections for t
16000 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d he meaning of "m
16010 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 odify" in this p
16020 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 aragraph..**.**
16030 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 When [sqlite3_pr
16040 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 epare_v2()] is u
16050 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 sed to prepare a
16060 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a statement, the.
16070 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 ** statement mig
16080 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 ht be re-prepare
16090 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 d during [sqlite
160a0 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 3_step()] due to
160b0 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 a .** schema ch
160c0 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 ange. Hence, th
160d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 e application sh
160e0 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 ould ensure that
160f0 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 the.** correct
16100 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
16110 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 ack remains in p
16120 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 lace during the
16130 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
16140 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ..**.** Note tha
16150 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 t the authorizer
16160 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
16170 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 oked only during
16180 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
16190 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 pare()] or its v
161a0 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 ariants. Author
161b0 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a ization is not.*
161c0 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 * performed duri
161d0 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 ng statement eva
161e0 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 luation in [sqli
161f0 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c te3_step()], unl
16200 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 ess.** as stated
16210 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 in the previous
16220 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 paragraph, sqli
16230 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b te3_step() invok
16240 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 es.** sqlite3_pr
16250 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 epare_v2() to re
16260 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d prepare a statem
16270 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65 ent after a sche
16280 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2a 0a 2a 2a ma change..**.**
16290 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
162a0 2a 20 5b 48 31 32 35 30 31 5d 20 5b 48 31 32 35 * [H12501] [H125
162b0 30 32 5d 20 5b 48 31 32 35 30 33 5d 20 5b 48 31 02] [H12503] [H1
162c0 32 35 30 34 5d 20 5b 48 31 32 35 30 35 5d 20 5b 2504] [H12505] [
162d0 48 31 32 35 30 36 5d 20 5b 48 31 32 35 30 37 5d H12506] [H12507]
162e0 20 5b 48 31 32 35 31 30 5d 0a 2a 2a 20 5b 48 31 [H12510].** [H1
162f0 32 35 31 31 5d 20 5b 48 31 32 35 31 32 5d 20 5b 2511] [H12512] [
16300 48 31 32 35 32 30 5d 20 5b 48 31 32 35 32 31 5d H12520] [H12521]
16310 20 5b 48 31 32 35 32 32 5d 0a 2a 2f 0a 53 51 4c [H12522].*/.SQL
16320 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
16330 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
16340 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a er(. sqlite3*,.
16350 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 int (*xAuth)(v
16360 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 oid*,int,const c
16370 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a har*,const char*
16380 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e ,const char*,con
16390 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 st char*),. voi
163a0 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a d *pUserData.);.
163b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
163c0 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 Authorizer Retu
163d0 72 6e 20 43 6f 64 65 73 20 7b 48 31 32 35 39 30 rn Codes {H12590
163e0 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a } <H12500>.**.**
163f0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 The [sqlite3_se
16400 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 t_authorizer | a
16410 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
16420 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 ck function] mus
16430 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 t.** return eith
16440 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f er [SQLITE_OK] o
16450 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 r one of these t
16460 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 wo constants in
16470 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e order.** to sign
16480 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 al SQLite whethe
16490 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 r or not the act
164a0 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 ion is permitted
164b0 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 . See the.** [s
164c0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
164d0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a rizer | authoriz
164e0 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e er documentation
164f0 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c ] for additional
16500 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e .** information.
16510 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
16520 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a TE_DENY 1 /*
16530 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 Abort the SQL s
16540 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e tatement with an
16550 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e error */.#defin
16560 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 e SQLITE_IGNORE
16570 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 2 /* Don't all
16580 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 ow access, but d
16590 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e on't generate an
165a0 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a error */../*.**
165b0 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f CAPI3REF: Autho
165c0 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 rizer Action Cod
165d0 65 73 20 7b 48 31 32 35 35 30 7d 20 3c 48 31 32 es {H12550} <H12
165e0 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 500>.**.** The [
165f0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
16600 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 orizer()] interf
16610 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 ace registers a
16620 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
16630 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 n.** that is inv
16640 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a oked to authoriz
16650 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 e certain SQL st
16660 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e atement actions.
16670 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 The.** second
16680 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
16690 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 callback is an
166a0 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 integer code tha
166b0 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 t specifies.** w
166c0 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 hat action is be
166d0 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 ing authorized.
166e0 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 These are the i
166f0 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f nteger action co
16700 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 des that.** the
16710 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
16720 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 ack may be passe
16730 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 d..**.** These a
16740 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 ction code value
16750 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b s signify what k
16760 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e ind of operation
16770 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 is to be.** aut
16780 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 horized. The 3r
16790 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 d and 4th parame
167a0 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 ters to the auth
167b0 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c orization.** cal
167c0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 lback function w
167d0 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 ill be parameter
167e0 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 s or NULL depend
167f0 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 ing on which of
16800 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 these.** codes i
16810 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 s used as the se
16820 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 cond parameter.
16830 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 The 5th paramet
16840 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 er to the.** aut
16850 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
16860 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 is the name of
16870 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d the database ("m
16880 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a ain", "temp",.**
16890 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 etc.) if applic
168a0 61 62 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70 able. The 6th p
168b0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
168c0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
168d0 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 ack.** is the na
168e0 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d me of the inner-
168f0 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 most trigger or
16900 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 view that is res
16910 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 ponsible for.**
16920 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d the access attem
16930 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 pt or NULL if th
16940 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 is access attemp
16950 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 t is directly fr
16960 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 om.** top-level
16970 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 SQL code..**.**
16980 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
16990 20 5b 48 31 32 35 35 31 5d 20 5b 48 31 32 35 35 [H12551] [H1255
169a0 32 5d 20 5b 48 31 32 35 35 33 5d 20 5b 48 31 32 2] [H12553] [H12
169b0 35 35 34 5d 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 554].*/./*******
169c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
169d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
169e0 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a **** 3rd *******
169f0 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a ***** 4th ******
16a00 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 *****/.#define S
16a10 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 QLITE_CREATE_IND
16a20 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 EX 1
16a30 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 /* Index Name
16a40 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
16a50 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
16a60 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c LITE_CREATE_TABL
16a70 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f E 2 /
16a80 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
16a90 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
16aa0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
16ab0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f ITE_CREATE_TEMP_
16ac0 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a INDEX 3 /*
16ad0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 Index Name
16ae0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
16af0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
16b00 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 TE_CREATE_TEMP_T
16b10 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 ABLE 4 /*
16b20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
16b30 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
16b40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
16b50 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 E_CREATE_TEMP_TR
16b60 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 IGGER 5 /* T
16b70 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 rigger Name T
16b80 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
16b90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
16ba0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 _CREATE_TEMP_VIE
16bb0 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 W 6 /* Vi
16bc0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 ew Name NU
16bd0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
16be0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
16bf0 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 CREATE_TRIGGER
16c00 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 7 /* Tri
16c10 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 gger Name Tab
16c20 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
16c30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
16c40 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 REATE_VIEW
16c50 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 8 /* View
16c60 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c Name NULL
16c70 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
16c80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 define SQLITE_DE
16c90 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 LETE
16ca0 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 9 /* Table
16cb0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
16cc0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
16cd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
16ce0 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 P_INDEX
16cf0 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 10 /* Index
16d00 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 Name Table
16d10 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
16d20 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
16d30 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 _TABLE
16d40 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 11 /* Table N
16d50 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
16d60 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
16d70 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
16d80 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 TEMP_INDEX
16d90 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 12 /* Index Na
16da0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 me Table Na
16db0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
16dc0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
16dd0 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 EMP_TABLE 1
16de0 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 3 /* Table Nam
16df0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
16e00 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
16e10 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 e SQLITE_DROP_TE
16e20 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 MP_TRIGGER 14
16e30 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 /* Trigger Na
16e40 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 me Table Name
16e50 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
16e60 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d SQLITE_DROP_TEM
16e70 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 P_VIEW 15
16e80 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 /* View Name
16e90 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
16ea0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
16eb0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 SQLITE_DROP_TRIG
16ec0 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 GER 16
16ed0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 /* Trigger Name
16ee0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
16ef0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
16f00 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 QLITE_DROP_VIEW
16f10 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 17
16f20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 /* View Name
16f30 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
16f40 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
16f50 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 LITE_INSERT
16f60 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 18 /
16f70 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
16f80 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
16f90 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
16fa0 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 ITE_PRAGMA
16fb0 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 19 /*
16fc0 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 Pragma Name
16fd0 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 1st arg or NULL
16fe0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
16ff0 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 TE_READ
17000 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 20 /*
17010 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
17020 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 Column Name
17030 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
17040 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 E_SELECT
17050 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 21 /* N
17060 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e ULL N
17070 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
17080 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
17090 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 _TRANSACTION
170a0 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 22 /* Op
170b0 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 eration NU
170c0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
170d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
170e0 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 UPDATE
170f0 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 23 /* Tab
17100 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c le Name Col
17110 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a umn Name */.
17120 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
17130 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 TTACH
17140 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 24 /* File
17150 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c name NULL
17160 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
17170 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 define SQLITE_DE
17180 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 TACH
17190 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 25 /* Datab
171a0 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 ase Name NULL
171b0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
171c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 efine SQLITE_ALT
171d0 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 ER_TABLE
171e0 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 26 /* Databa
171f0 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 se Name Table
17200 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
17210 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e fine SQLITE_REIN
17220 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 DEX
17230 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 27 /* Index N
17240 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
17250 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
17260 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 ine SQLITE_ANALY
17270 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ZE
17280 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 28 /* Table Na
17290 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
172a0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
172b0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
172c0 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 _VTABLE 2
172d0 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 9 /* Table Nam
172e0 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 e Module Na
172f0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e me */.#defin
17300 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 e SQLITE_DROP_VT
17310 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 ABLE 30
17320 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
17330 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d Module Nam
17340 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 e */.#define
17350 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e SQLITE_FUNCTION
17360 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 31
17370 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 /* NULL
17380 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 Function Na
17390 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 me */.#define
173a0 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 SQLITE_SAVEPOINT
173b0 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20 32
173c0 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 /* Operation
173d0 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 Savepoint Na
173e0 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 me */.#define S
173f0 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 QLITE_COPY
17400 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 0
17410 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 /* No longer use
17420 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 d */../*.** CAPI
17430 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 3REF: Tracing An
17440 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 d Profiling Func
17450 74 69 6f 6e 73 20 7b 48 31 32 32 38 30 7d 20 3c tions {H12280} <
17460 53 36 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 S60400>.** EXPER
17470 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 IMENTAL.**.** Th
17480 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 ese routines reg
17490 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 ister callback f
174a0 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 unctions that ca
174b0 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a n be used for.**
174c0 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f tracing and pro
174d0 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 filing the execu
174e0 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 tion of SQL stat
174f0 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 ements..**.** Th
17500 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
17510 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 ion registered b
17520 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 y sqlite3_trace(
17530 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a ) is invoked at.
17540 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 ** various times
17550 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 when an SQL sta
17560 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 tement is being
17570 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f run by [sqlite3_
17580 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 step()]..** The
17590 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
175a0 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 a UTF-8 renderi
175b0 6e 67 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 ng of the SQL st
175c0 61 74 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a 20 atement text.**
175d0 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 as the statement
175e0 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 first begins ex
175f0 65 63 75 74 69 6e 67 2e 20 20 41 64 64 69 74 69 ecuting. Additi
17600 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 6f onal callbacks o
17610 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 ccur.** as each
17620 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f triggered subpro
17630 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e gram is entered.
17640 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 The callbacks
17650 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 for triggers.**
17660 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 contain a UTF-8
17670 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 SQL comment that
17680 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 identifies the
17690 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 trigger..**.** T
176a0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 he callback func
176b0 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 tion registered
176c0 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 by sqlite3_profi
176d0 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a le() is invoked.
176e0 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 ** as each SQL s
176f0 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 tatement finishe
17700 73 2e 20 20 54 68 65 20 70 72 6f 66 69 6c 65 20 s. The profile
17710 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e callback contain
17720 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 s.** the origina
17730 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 l statement text
17740 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 and an estimate
17750 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 of wall-clock t
17760 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f ime.** of how lo
17770 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e ng that statemen
17780 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a t took to run..*
17790 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
177a0 73 3a 0a 2a 2a 20 5b 48 31 32 32 38 31 5d 20 5b s:.** [H12281] [
177b0 48 31 32 32 38 32 5d 20 5b 48 31 32 32 38 33 5d H12282] [H12283]
177c0 20 5b 48 31 32 32 38 34 5d 20 5b 48 31 32 32 38 [H12284] [H1228
177d0 35 5d 20 5b 48 31 32 32 38 37 5d 20 5b 48 31 32 5] [H12287] [H12
177e0 32 38 38 5d 20 5b 48 31 32 32 38 39 5d 0a 2a 2a 288] [H12289].**
177f0 20 5b 48 31 32 32 39 30 5d 0a 2a 2f 0a 53 51 4c [H12290].*/.SQL
17800 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 ITE_API SQLITE_E
17810 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 XPERIMENTAL void
17820 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 *sqlite3_trace(
17830 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a sqlite3*, void(*
17840 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f xTrace)(void*,co
17850 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 nst char*), void
17860 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 *);.SQLITE_API S
17870 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 QLITE_EXPERIMENT
17880 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 AL void *sqlite3
17890 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 _profile(sqlite3
178a0 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f *,. void(*xPro
178b0 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 file)(void*,cons
178c0 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f t char*,sqlite3_
178d0 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b uint64), void*);
178e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
178f0 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 : Query Progress
17900 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 Callbacks {H129
17910 31 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 10} <S60400>.**.
17920 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
17930 63 6f 6e 66 69 67 75 72 65 73 20 61 20 63 61 6c configures a cal
17940 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d lback function -
17950 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73 73 the.** progress
17960 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74 callback - that
17970 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 is invoked peri
17980 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 odically during
17990 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 long.** running
179a0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
179b0 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 3_exec()], [sqli
179c0 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 0a te3_step()] and.
179d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f ** [sqlite3_get_
179e0 74 61 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65 78 table()]. An ex
179f0 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 ample use for th
17a00 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 is.** interface
17a10 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 is to keep a GUI
17a20 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 updated during
17a30 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a a large query..*
17a40 2a 0a 2a 2a 20 49 66 20 74 68 65 20 70 72 6f 67 *.** If the prog
17a50 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 ress callback re
17a60 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 turns non-zero,
17a70 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 the operation is
17a80 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e .** interrupted.
17a90 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 This feature c
17aa0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d an be used to im
17ab0 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 plement a.** "Ca
17ac0 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 ncel" button on
17ad0 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 a GUI progress d
17ae0 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a ialog box..**.**
17af0 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 The progress ha
17b00 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 64 ndler must not d
17b10 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 o anything that
17b20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 will modify.** t
17b30 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
17b40 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f ection that invo
17b50 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 ked the progress
17b60 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 handler..** Not
17b70 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f e that [sqlite3_
17b80 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e prepare_v2()] an
17b90 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 d [sqlite3_step(
17ba0 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 )] both modify t
17bb0 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 heir.** database
17bc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 connections for
17bd0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 the meaning of
17be0 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 "modify" in this
17bf0 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a paragraph..**.*
17c00 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
17c10 2a 2a 20 5b 48 31 32 39 31 31 5d 20 5b 48 31 32 ** [H12911] [H12
17c20 39 31 32 5d 20 5b 48 31 32 39 31 33 5d 20 5b 48 912] [H12913] [H
17c30 31 32 39 31 34 5d 20 5b 48 31 32 39 31 35 5d 20 12914] [H12915]
17c40 5b 48 31 32 39 31 36 5d 20 5b 48 31 32 39 31 37 [H12916] [H12917
17c50 5d 20 5b 48 31 32 39 31 38 5d 0a 2a 2a 0a 2a 2f ] [H12918].**.*/
17c60 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
17c70 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 sqlite3_progres
17c80 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 s_handler(sqlite
17c90 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 3*, int, int(*)(
17ca0 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a void*), void*);.
17cb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
17cc0 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 Opening A New D
17cd0 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 atabase Connecti
17ce0 6f 6e 20 7b 48 31 32 37 30 30 7d 20 3c 53 34 30 on {H12700} <S40
17cf0 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 200>.**.** These
17d00 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 routines open a
17d10 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 n SQLite databas
17d20 65 20 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d e file whose nam
17d30 65 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 e is given by th
17d40 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 e.** filename ar
17d50 67 75 6d 65 6e 74 2e 20 54 68 65 20 66 69 6c 65 gument. The file
17d60 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 name argument is
17d70 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 interpreted as
17d80 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c UTF-8 for.** sql
17d90 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 ite3_open() and
17da0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
17db0 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 ) and as UTF-16
17dc0 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 in the native by
17dd0 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 te.** order for
17de0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
17df0 2e 20 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f . A [database co
17e00 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 nnection] handle
17e10 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 is usually.** r
17e20 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 eturned in *ppDb
17e30 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 , even if an err
17e40 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 or occurs. The
17e50 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 only exception i
17e60 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c s that.** if SQL
17e70 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f ite is unable to
17e80 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 allocate memory
17e90 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 to hold the [sq
17ea0 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a lite3] object,.*
17eb0 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 * a NULL will be
17ec0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 written into *p
17ed0 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 pDb instead of a
17ee0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
17ef0 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a [sqlite3].** obj
17f00 65 63 74 2e 20 49 66 20 74 68 65 20 64 61 74 61 ect. If the data
17f10 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 base is opened (
17f20 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 and/or created)
17f30 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 successfully, th
17f40 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b en.** [SQLITE_OK
17f50 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 ] is returned.
17f60 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 Otherwise an [er
17f70 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 ror code] is ret
17f80 75 72 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20 5b urned. The.** [
17f90 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 sqlite3_errmsg()
17fa0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 ] or [sqlite3_er
17fb0 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e rmsg16()] routin
17fc0 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 es can be used t
17fd0 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 o obtain.** an E
17fe0 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 nglish language
17ff0 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 description of t
18000 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 he error..**.**
18010 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f The default enco
18020 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 ding for the dat
18030 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 abase will be UT
18040 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 F-8 if.** sqlite
18050 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 3_open() or sqli
18060 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 te3_open_v2() is
18070 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 called and.** U
18080 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 TF-16 in the nat
18090 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 ive byte order i
180a0 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 f sqlite3_open16
180b0 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a () is used..**.*
180c0 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 * Whether or not
180d0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 an error occurs
180e0 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e when it is open
180f0 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a ed, resources.**
18100 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
18110 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
18120 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c onnection] handl
18130 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 e should be rele
18140 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 ased by.** passi
18150 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 ng it to [sqlite
18160 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 3_close()] when
18170 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 it is no longer
18180 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 required..**.**
18190 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e The sqlite3_open
181a0 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 _v2() interface
181b0 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 works like sqlit
181c0 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 e3_open().** exc
181d0 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 ept that it acce
181e0 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e pts two addition
181f0 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f al parameters fo
18200 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e r additional con
18210 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 trol.** over the
18220 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f new database co
18230 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 nnection. The f
18240 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 63 lags parameter c
18250 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a an take one of.*
18260 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 * the following
18270 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 three values, op
18280 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 tionally combine
18290 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b d with the .** [
182a0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 SQLITE_OPEN_NOMU
182b0 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 TEX], [SQLITE_OP
182c0 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b EN_FULLMUTEX], [
182d0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 SQLITE_OPEN_SHAR
182e0 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 61 6e 64 EDCACHE],.** and
182f0 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e /or [SQLITE_OPEN
18300 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 _PRIVATECACHE] f
18310 6c 61 67 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e lags:.**.** <dl>
18320 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f .** <dt>[SQLITE_
18330 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f OPEN_READONLY]</
18340 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 dt>.** <dd>The d
18350 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 atabase is opene
18360 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d d in read-only m
18370 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 ode. If the dat
18380 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a abase does not.*
18390 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c * already exist,
183a0 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 an error is ret
183b0 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a urned.</dd>.**.*
183c0 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 * <dt>[SQLITE_OP
183d0 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 EN_READWRITE]</d
183e0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 t>.** <dd>The da
183f0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 tabase is opened
18400 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 for reading and
18410 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 writing if poss
18420 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 ible, or reading
18430 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 .** only if the
18440 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 file is write pr
18450 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f otected by the o
18460 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e perating system.
18470 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 In either.** c
18480 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 ase the database
18490 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 must already ex
184a0 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 ist, otherwise a
184b0 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 n error is retur
184c0 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ned.</dd>.**.**
184d0 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e <dt>[SQLITE_OPEN
184e0 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 _READWRITE] | [S
184f0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
18500 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 E]</dt>.** <dd>T
18510 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f he database is o
18520 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e pened for readin
18530 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 g and writing, a
18540 6e 64 20 69 73 20 63 72 65 61 74 65 73 20 69 74 nd is creates it
18550 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e if.** it does n
18560 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 ot already exist
18570 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65 . This is the be
18580 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 havior that is a
18590 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a lways used for.*
185a0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 * sqlite3_open()
185b0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 and sqlite3_ope
185c0 6e 31 36 28 29 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c n16().</dd>.** <
185d0 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 /dl>.**.** If th
185e0 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 e 3rd parameter
185f0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f to sqlite3_open_
18600 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 v2() is not one
18610 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e of the.** combin
18620 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f ations shown abo
18630 76 65 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 ve or one of the
18640 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 combinations sh
18650 6f 77 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e own above combin
18660 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b ed.** with the [
18670 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 SQLITE_OPEN_NOMU
18680 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 TEX], [SQLITE_OP
18690 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 0a 2a EN_FULLMUTEX],.*
186a0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 * [SQLITE_OPEN_S
186b0 48 41 52 45 44 43 41 43 48 45 5d 20 61 6e 64 2f HAREDCACHE] and/
186c0 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f or [SQLITE_OPEN_
186d0 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 SHAREDCACHE] fla
186e0 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 gs,.** then the
186f0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 behavior is unde
18700 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 fined..**.** If
18710 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e the [SQLITE_OPEN
18720 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 _NOMUTEX] flag i
18730 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 s set, then the
18740 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
18750 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 ion.** opens in
18760 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 the multi-thread
18770 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
18780 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 ] as long as the
18790 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a single-thread.*
187a0 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 * mode has not b
187b0 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 een set at compi
187c0 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 le-time or start
187d0 2d 74 69 6d 65 2e 20 20 49 66 20 74 68 65 0a 2a -time. If the.*
187e0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 * [SQLITE_OPEN_F
187f0 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 ULLMUTEX] flag i
18800 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 s set then the d
18810 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
18820 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 on opens.** in t
18830 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 he serialized [t
18840 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 hreading mode] u
18850 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 nless single-thr
18860 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 ead was.** previ
18870 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 ously selected a
18880 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f t compile-time o
18890 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a r start-time..**
188a0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 The [SQLITE_OPE
188b0 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 N_SHAREDCACHE] f
188c0 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 lag causes the d
188d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
188e0 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 on to be.** elig
188f0 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 ible to use [sha
18900 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c red cache mode],
18910 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 regardless of w
18920 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 hether or not sh
18930 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 ared.** cache is
18940 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b enabled using [
18950 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 sqlite3_enable_s
18960 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 hared_cache()].
18970 20 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f The.** [SQLITE_
18980 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 OPEN_PRIVATECACH
18990 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 E] flag causes t
189a0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
189b0 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a ection to not.**
189c0 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 participate in
189d0 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f [shared cache mo
189e0 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 de] even if it i
189f0 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a s enabled..**.**
18a00 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 If the filename
18a10 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 is ":memory:",
18a20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 then a private,
18a30 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d temporary in-mem
18a40 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 ory database.**
18a50 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 is created for t
18a60 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 he connection.
18a70 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 This in-memory d
18a80 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e atabase will van
18a90 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 ish when.** the
18aa0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
18ab0 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 ion is closed.
18ac0 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 Future versions
18ad0 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a of SQLite might.
18ae0 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 ** make use of a
18af0 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 dditional specia
18b00 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 l filenames that
18b10 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 begin with the
18b20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a ":" character..*
18b30 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e * It is recommen
18b40 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 ded that when a
18b50 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d database filenam
18b60 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 e actually does
18b70 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 begin with.** a
18b80 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f ":" character yo
18b90 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 u should prefix
18ba0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 the filename wit
18bb0 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 h a pathname suc
18bc0 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 h as.** "./" to
18bd0 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e avoid ambiguity.
18be0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 .**.** If the fi
18bf0 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 lename is an emp
18c00 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 ty string, then
18c10 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f a private, tempo
18c20 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 rary.** on-disk
18c30 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 database will be
18c40 20 63 72 65 61 74 65 64 2e 20 20 54 68 69 73 20 created. This
18c50 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65 private database
18c60 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f will be.** auto
18c70 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 matically delete
18c80 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 d as soon as the
18c90 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
18ca0 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a tion is closed..
18cb0 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 **.** The fourth
18cc0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
18cd0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
18ce0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 is the name of t
18cf0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 he.** [sqlite3_v
18d00 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 fs] object that
18d10 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 defines the oper
18d20 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 ating system int
18d30 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 erface that.** t
18d40 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 he new database
18d50 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c connection shoul
18d60 64 20 75 73 65 2e 20 20 49 66 20 74 68 65 20 66 d use. If the f
18d70 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
18d80 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 is.** a NULL poi
18d90 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 nter then the de
18da0 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 fault [sqlite3_v
18db0 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 fs] object is us
18dc0 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 ed..**.** <b>Not
18dd0 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 e to Windows use
18de0 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 rs:</b> The enc
18df0 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 oding used for t
18e00 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 he filename argu
18e10 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 ment.** of sqlit
18e20 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 e3_open() and sq
18e30 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
18e40 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e must be UTF-8, n
18e50 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 ot whatever.** c
18e60 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 odepage is curre
18e70 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 ntly defined. F
18e80 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e ilenames contain
18e90 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 ing internationa
18ea0 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 l.** characters
18eb0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 must be converte
18ec0 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 d to UTF-8 prior
18ed0 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d to passing them
18ee0 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 into.** sqlite3
18ef0 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 _open() or sqlit
18f00 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a e3_open_v2()..**
18f10 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
18f20 3a 0a 2a 2a 20 5b 48 31 32 37 30 31 5d 20 5b 48 :.** [H12701] [H
18f30 31 32 37 30 32 5d 20 5b 48 31 32 37 30 33 5d 20 12702] [H12703]
18f40 5b 48 31 32 37 30 34 5d 20 5b 48 31 32 37 30 36 [H12704] [H12706
18f50 5d 20 5b 48 31 32 37 30 37 5d 20 5b 48 31 32 37 ] [H12707] [H127
18f60 30 39 5d 20 5b 48 31 32 37 31 31 5d 0a 2a 2a 20 09] [H12711].**
18f70 5b 48 31 32 37 31 32 5d 20 5b 48 31 32 37 31 33 [H12712] [H12713
18f80 5d 20 5b 48 31 32 37 31 34 5d 20 5b 48 31 32 37 ] [H12714] [H127
18f90 31 37 5d 20 5b 48 31 32 37 31 39 5d 20 5b 48 31 17] [H12719] [H1
18fa0 32 37 32 31 5d 20 5b 48 31 32 37 32 33 5d 0a 2a 2721] [H12723].*
18fb0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
18fc0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 sqlite3_open(.
18fd0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c const char *fil
18fe0 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 ename, /* Data
18ff0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 base filename (U
19000 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 TF-8) */. sqlit
19010 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 e3 **ppDb
19020 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 /* OUT: SQLit
19030 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 e db handle */.)
19040 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
19050 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 sqlite3_open16(
19060 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 . const void *f
19070 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 ilename, /* Da
19080 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 tabase filename
19090 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 (UTF-16) */. sq
190a0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 lite3 **ppDb
190b0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 /* OUT: SQ
190c0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a Lite db handle *
190d0 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 /.);.SQLITE_API
190e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e int sqlite3_open
190f0 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 _v2(. const cha
19100 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f r *filename, /
19110 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e * Database filen
19120 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 ame (UTF-8) */.
19130 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c sqlite3 **ppDb,
19140 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a /* OUT:
19150 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c SQLite db handl
19160 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 e */. int flags
19170 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f , /
19180 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e * Flags */. con
19190 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 st char *zVfs
191a0 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 /* Name of
191b0 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 VFS module to us
191c0 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 e */.);../*.** C
191d0 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 API3REF: Error C
191e0 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 odes And Message
191f0 73 20 7b 48 31 32 38 30 30 7d 20 3c 53 36 30 32 s {H12800} <S602
19200 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 00>.**.** The sq
19210 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 lite3_errcode()
19220 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
19230 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 s the numeric [r
19240 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a esult code] or.*
19250 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 * [extended resu
19260 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 lt code] for the
19270 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 most recent fai
19280 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 led sqlite3_* AP
19290 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 I call.** associ
192a0 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 ated with a [dat
192b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
192c0 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 ]. If a prior AP
192d0 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a I call failed.**
192e0 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 but the most re
192f0 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 cent API call su
19300 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 cceeded, the ret
19310 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a urn value from.*
19320 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 * sqlite3_errcod
19330 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 e() is undefined
19340 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 . The sqlite3_e
19350 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 xtended_errcode(
19360 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 ).** interface i
19370 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 s the same excep
19380 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 t that it always
19390 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a returns the .**
193a0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c [extended resul
193b0 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 t code] even whe
193c0 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c n extended resul
193d0 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 t codes are.** d
193e0 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 isabled..**.** T
193f0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 he sqlite3_errms
19400 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f g() and sqlite3_
19410 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 errmsg16() retur
19420 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 n English-langua
19430 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 ge.** text that
19440 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 describes the er
19450 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 ror, as either U
19460 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 TF-8 or UTF-16 r
19470 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 espectively..**
19480 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 Memory to hold t
19490 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 he error message
194a0 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 string is manag
194b0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a ed internally..*
194c0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f * The applicatio
194d0 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 n does not need
194e0 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 to worry about f
194f0 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c reeing the resul
19500 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 t..** However, t
19510 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 he error string
19520 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 might be overwri
19530 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 tten or dealloca
19540 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 ted by.** subseq
19550 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 uent calls to ot
19560 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 her SQLite inter
19570 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 0a face functions..
19580 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 **.** When the s
19590 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 erialized [threa
195a0 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e ding mode] is in
195b0 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 use, it might b
195c0 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 e the.** case th
195d0 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f at a second erro
195e0 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 r occurs on a se
195f0 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e parate thread in
19600 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 between.** the
19610 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 time of the firs
19620 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 t error and the
19630 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e call to these in
19640 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 terfaces..** Whe
19650 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 n that happens,
19660 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 the second error
19670 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 will be reporte
19680 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a d since these.**
19690 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 interfaces alwa
196a0 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f ys report the mo
196b0 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 st recent result
196c0 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 . To avoid.** t
196d0 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 his, each thread
196e0 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c can obtain excl
196f0 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 usive use of the
19700 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
19710 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 ction] D.** by i
19720 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 nvoking [sqlite3
19730 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 _mutex_enter]([s
19740 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d qlite3_db_mutex]
19750 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 (D)) before begi
19760 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 nning.** to use
19770 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b D and invoking [
19780 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 sqlite3_mutex_le
19790 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 ave]([sqlite3_db
197a0 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 _mutex](D)) afte
197b0 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 r.** all calls t
197c0 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 o the interfaces
197d0 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65 listed here are
197e0 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a completed..**.*
197f0 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 * If an interfac
19800 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c e fails with SQL
19810 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 ITE_MISUSE, that
19820 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 means the inter
19830 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f face.** was invo
19840 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 ked incorrectly
19850 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 by the applicati
19860 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 on. In that cas
19870 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 e, the.** error
19880 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 code and message
19890 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 may or may not
198a0 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 be set..**.** Re
198b0 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
198c0 48 31 32 38 30 31 5d 20 5b 48 31 32 38 30 32 5d H12801] [H12802]
198d0 20 5b 48 31 32 38 30 33 5d 20 5b 48 31 32 38 30 [H12803] [H1280
198e0 37 5d 20 5b 48 31 32 38 30 38 5d 20 5b 48 31 32 7] [H12808] [H12
198f0 38 30 39 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 809].*/.SQLITE_A
19900 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 PI int sqlite3_e
19910 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a rrcode(sqlite3 *
19920 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 db);.SQLITE_API
19930 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 int sqlite3_exte
19940 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c nded_errcode(sql
19950 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 ite3 *db);.SQLIT
19960 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 E_API const char
19970 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 *sqlite3_errmsg
19980 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 (sqlite3*);.SQLI
19990 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 TE_API const voi
199a0 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 d *sqlite3_errms
199b0 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a g16(sqlite3*);..
199c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
199d0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 SQL Statement Ob
199e0 6a 65 63 74 20 7b 48 31 33 30 30 30 7d 20 3c 48 ject {H13000} <H
199f0 31 33 30 31 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 13010>.** KEYWOR
19a00 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 DS: {prepared st
19a10 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 atement} {prepar
19a20 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a ed statements}.*
19a30 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 *.** An instance
19a40 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 of this object
19a50 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e represents a sin
19a60 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e gle SQL statemen
19a70 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 t..** This objec
19a80 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b t is variously k
19a90 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 nown as a "prepa
19aa0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f red statement" o
19ab0 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 r a.** "compiled
19ac0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 SQL statement"
19ad0 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 or simply as a "
19ae0 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a statement"..**.*
19af0 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 * The life of a
19b00 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 statement object
19b10 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 goes something
19b20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a like this:.**.**
19b30 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 <ol>.** <li> Cr
19b40 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 eate the object
19b50 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 using [sqlite3_p
19b60 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
19b70 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 a related.**
19b80 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c function..** <
19b90 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 li> Bind values
19ba0 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 to [host paramet
19bb0 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 ers] using the s
19bc0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a qlite3_bind_*().
19bd0 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 ** interfac
19be0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 es..** <li> Run
19bf0 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 the SQL by calli
19c00 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ng [sqlite3_step
19c10 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 ()] one or more
19c20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 times..** <li> R
19c30 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 eset the stateme
19c40 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 nt using [sqlite
19c50 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 3_reset()] then
19c60 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 go back.**
19c70 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 to step 2. Do t
19c80 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 his zero or more
19c90 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 times..** <li>
19ca0 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 Destroy the obje
19cb0 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ct using [sqlite
19cc0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 3_finalize()]..*
19cd0 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 * </ol>.**.** Re
19ce0 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 fer to documenta
19cf0 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 tion on individu
19d00 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 al methods above
19d10 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a for additional.
19d20 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a ** information..
19d30 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
19d40 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 t sqlite3_stmt s
19d50 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a qlite3_stmt;../*
19d60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 .** CAPI3REF: Ru
19d70 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 20 7b 48 n-time Limits {H
19d80 31 32 37 36 30 7d 20 3c 53 32 30 36 30 30 3e 0a 12760} <S20600>.
19d90 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 **.** This inter
19da0 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 face allows the
19db0 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 size of various
19dc0 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 constructs to be
19dd0 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 limited.** on a
19de0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 connection by c
19df0 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e onnection basis.
19e00 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 The first para
19e10 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 meter is the.**
19e20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
19e30 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 tion] whose limi
19e40 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f t is to be set o
19e50 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a r queried. The.
19e60 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 ** second parame
19e70 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 ter is one of th
19e80 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 e [limit categor
19e90 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 ies] that define
19ea0 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 a.** class of c
19eb0 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 onstructs to be
19ec0 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 size limited. T
19ed0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
19ee0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 er is the.** new
19ef0 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 limit for that
19f00 63 6f 6e 73 74 72 75 63 74 2e 20 20 54 68 65 20 construct. The
19f10 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
19f20 20 74 68 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 0a the old limit..
19f30 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 65 77 **.** If the new
19f40 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 limit is a nega
19f50 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 tive number, the
19f60 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e limit is unchan
19f70 67 65 64 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20 ged..** For the
19f80 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 6f limit category o
19f90 66 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 f SQLITE_LIMIT_X
19fa0 59 5a 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a YZ there is a .*
19fb0 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 * [limits | hard
19fc0 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a upper bound].**
19fd0 20 73 65 74 20 62 79 20 61 20 63 6f 6d 70 69 6c set by a compil
19fe0 65 2d 74 69 6d 65 20 43 20 70 72 65 70 72 6f 63 e-time C preproc
19ff0 65 73 73 6f 72 20 6d 61 63 72 6f 20 6e 61 6d 65 essor macro name
1a000 64 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 d .** [limits |
1a010 53 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a 5d 2e SQLITE_MAX_XYZ].
1a020 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 .** (The "_LIMIT
1a030 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 _" in the name i
1a040 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d s changed to "_M
1a050 41 58 5f 22 2e 29 0a 2a 2a 20 41 74 74 65 6d 70 AX_".).** Attemp
1a060 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 ts to increase a
1a070 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 limit above its
1a080 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e hard upper boun
1a090 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c d are.** silentl
1a0a0 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 y truncated to t
1a0b0 68 65 20 68 61 72 64 20 75 70 70 65 72 20 6c 69 he hard upper li
1a0c0 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 20 74 mit..**.** Run t
1a0d0 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 ime limits are i
1a0e0 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 ntended for use
1a0f0 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 in applications
1a100 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 that manage.** b
1a110 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e oth their own in
1a120 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 ternal database
1a130 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 and also databas
1a140 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 es that are cont
1a150 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 rolled.** by unt
1a160 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 rusted external
1a170 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 sources. An exa
1a180 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e mple application
1a190 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 might be a.** w
1a1a0 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 eb browser that
1a1b0 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 has its own data
1a1c0 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e bases for storin
1a1d0 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a g history and.**
1a1e0 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 separate databa
1a1f0 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 ses controlled b
1a200 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 y JavaScript app
1a210 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f lications downlo
1a220 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 aded.** off the
1a230 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 Internet. The i
1a240 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 nternal database
1a250 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 s can be given t
1a260 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 he.** large, def
1a270 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 ault limits. Da
1a280 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 tabases managed
1a290 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 by external sour
1a2a0 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 ces can.** be gi
1a2b0 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 ven much smaller
1a2c0 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 limits designed
1a2d0 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 to prevent a de
1a2e0 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a nial of service.
1a2f0 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 ** attack. Deve
1a300 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 lopers might als
1a310 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 o want to use th
1a320 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 e [sqlite3_set_a
1a330 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 uthorizer()].**
1a340 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 interface to fur
1a350 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 ther control unt
1a360 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 rusted SQL. The
1a370 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 size of the dat
1a380 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 abase.** created
1a390 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 by an untrusted
1a3a0 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 script can be c
1a3b0 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 ontained using t
1a3c0 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f he.** [max_page_
1a3d0 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e count] [PRAGMA].
1a3e0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 .**.** New run-t
1a3f0 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f ime limit catego
1a400 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 ries may be adde
1a410 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 d in future rele
1a420 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 ases..**.** Requ
1a430 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
1a440 32 37 36 32 5d 20 5b 48 31 32 37 36 36 5d 20 5b 2762] [H12766] [
1a450 48 31 32 37 36 39 5d 0a 2a 2f 0a 53 51 4c 49 54 H12769].*/.SQLIT
1a460 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
1a470 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 3_limit(sqlite3*
1a480 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 , int id, int ne
1a490 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 wVal);../*.** CA
1a4a0 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 PI3REF: Run-Time
1a4b0 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 Limit Categorie
1a4c0 73 20 7b 48 31 32 37 39 30 7d 20 3c 48 31 32 37 s {H12790} <H127
1a4d0 36 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 60>.** KEYWORDS:
1a4e0 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 {limit category
1a4f0 7d 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 } {limit categor
1a500 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ies}.**.** These
1a510 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e constants defin
1a520 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 e various perfor
1a530 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 mance limits.**
1a540 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 that can be lowe
1a550 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 red at run-time
1a560 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c using [sqlite3_l
1a570 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 imit()]..** The
1a580 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 synopsis of the
1a590 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 meanings of the
1a5a0 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 various limits i
1a5b0 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a s shown below..*
1a5c0 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 * Additional inf
1a5d0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 ormation is avai
1a5e0 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 lable at [limits
1a5f0 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c | Limits in SQL
1a600 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e ite]..**.** <dl>
1a610 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c .** <dt>SQLITE_L
1a620 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e IMIT_LENGTH</dt>
1a630 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
1a640 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 mum size of any
1a650 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f string or BLOB o
1a660 72 20 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e r table row.<dd>
1a670 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
1a680 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 E_LIMIT_SQL_LENG
1a690 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 TH</dt>.** <dd>T
1a6a0 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 he maximum lengt
1a6b0 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 h of an SQL stat
1a6c0 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a ement.</dd>.**.*
1a6d0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d * <dt>SQLITE_LIM
1a6e0 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a IT_COLUMN</dt>.*
1a6f0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
1a700 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 m number of colu
1a710 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 mns in a table d
1a720 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 efinition or in
1a730 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 the.** result se
1a740 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 t of a [SELECT]
1a750 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e or the maximum n
1a760 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
1a770 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 in an index.**
1a780 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 or in an ORDER B
1a790 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c Y or GROUP BY cl
1a7a0 61 75 73 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ause.</dd>.**.**
1a7b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 <dt>SQLITE_LIMI
1a7c0 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 T_EXPR_DEPTH</dt
1a7d0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
1a7e0 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 imum depth of th
1a7f0 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 e parse tree on
1a800 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c any expression.<
1a810 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
1a820 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 QLITE_LIMIT_COMP
1a830 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e OUND_SELECT</dt>
1a840 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
1a850 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 mum number of te
1a860 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e rms in a compoun
1a870 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 d SELECT stateme
1a880 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c nt.</dd>.**.** <
1a890 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
1a8a0 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 VDBE_OP</dt>.**
1a8b0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
1a8c0 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 number of instru
1a8d0 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 ctions in a virt
1a8e0 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 ual machine prog
1a8f0 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 ram.** used to i
1a900 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 mplement an SQL
1a910 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a statement.</dd>.
1a920 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
1a930 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f _LIMIT_FUNCTION_
1a940 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ARG</dt>.** <dd>
1a950 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
1a960 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 er of arguments
1a970 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f on a function.</
1a980 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
1a990 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 LITE_LIMIT_ATTAC
1a9a0 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e HED</dt>.** <dd>
1a9b0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
1a9c0 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 er of [ATTACH |
1a9d0 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 attached databas
1a9e0 65 73 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 es].</dd>.**.**
1a9f0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
1aa00 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 _LIKE_PATTERN_LE
1aa10 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 NGTH</dt>.** <dd
1aa20 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e >The maximum len
1aa30 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 gth of the patte
1aa40 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 rn argument to t
1aa50 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 he [LIKE] or.**
1aa60 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 [GLOB] operators
1aa70 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
1aa80 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 >SQLITE_LIMIT_VA
1aa90 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 RIABLE_NUMBER</d
1aaa0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
1aab0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
1aac0 76 61 72 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 variables in an
1aad0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 SQL statement th
1aae0 61 74 20 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 at can.** be bou
1aaf0 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c nd.</dd>.**.** <
1ab00 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
1ab10 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 TRIGGER_DEPTH</d
1ab20 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
1ab30 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 ximum depth of r
1ab40 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 ecursion for tri
1ab50 67 67 65 72 73 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c ggers.</dd>.** <
1ab60 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 /dl>.*/.#define
1ab70 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e SQLITE_LIMIT_LEN
1ab80 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 GTH
1ab90 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 0.#define
1aba0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 SQLITE_LIMIT_SQ
1abb0 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 L_LENGTH
1abc0 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 1.#defin
1abd0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 e SQLITE_LIMIT_C
1abe0 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 OLUMN
1abf0 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 2.#defi
1ac00 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
1ac10 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 EXPR_DEPTH
1ac20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 3.#def
1ac30 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
1ac40 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 _COMPOUND_SELECT
1ac50 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 4.#de
1ac60 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
1ac70 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 T_VDBE_OP
1ac80 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 5.#d
1ac90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
1aca0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 IT_FUNCTION_ARG
1acb0 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 6.#
1acc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
1acd0 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 MIT_ATTACHED
1ace0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 7.
1acf0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
1ad00 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 IMIT_LIKE_PATTER
1ad10 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 N_LENGTH 8
1ad20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1ad30 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e LIMIT_VARIABLE_N
1ad40 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 UMBER
1ad50 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 9.#define SQLITE
1ad60 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 _LIMIT_TRIGGER_D
1ad70 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 EPTH
1ad80 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 10../*.** CAPI3R
1ad90 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e EF: Compiling An
1ada0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b SQL Statement {
1adb0 48 31 33 30 31 30 7d 20 3c 53 31 30 30 30 30 3e H13010} <S10000>
1adc0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 .** KEYWORDS: {S
1add0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d QL statement com
1ade0 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 piler}.**.** To
1adf0 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 execute an SQL q
1ae00 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 uery, it must fi
1ae10 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 rst be compiled
1ae20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 into a byte-code
1ae30 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e .** program usin
1ae40 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 g one of these r
1ae50 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 outines..**.** T
1ae60 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
1ae70 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 t, "db", is a [d
1ae80 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1ae90 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f on] obtained fro
1aea0 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 m a.** prior suc
1aeb0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 cessful call to
1aec0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
1aed0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f , [sqlite3_open_
1aee0 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c v2()] or.** [sql
1aef0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 ite3_open16()].
1af00 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f The database co
1af10 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f nnection must no
1af20 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 t have been clos
1af30 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 ed..**.** The se
1af40 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 cond argument, "
1af50 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 zSql", is the st
1af60 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f atement to be co
1af70 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a mpiled, encoded.
1af80 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 ** as either UTF
1af90 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 -8 or UTF-16. T
1afa0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 he sqlite3_prepa
1afb0 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 re() and sqlite3
1afc0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a _prepare_v2().**
1afd0 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 interfaces use
1afe0 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 UTF-8, and sqlit
1aff0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 e3_prepare16() a
1b000 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nd sqlite3_prepa
1b010 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 re16_v2().** use
1b020 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 49 UTF-16..**.** I
1b030 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 f the nByte argu
1b040 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 ment is less tha
1b050 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 n zero, then zSq
1b060 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 l is read up to
1b070 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 the.** first zer
1b080 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 49 66 o terminator. If
1b090 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 nByte is non-ne
1b0a0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 gative, then it
1b0b0 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a is the maximum.*
1b0c0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 * number of byt
1b0d0 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 es read from zSq
1b0e0 6c 2e 20 20 57 68 65 6e 20 6e 42 79 74 65 20 69 l. When nByte i
1b0f0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 s non-negative,
1b100 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 the.** zSql stri
1b110 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 ng ends at eithe
1b120 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 r the first '\00
1b130 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 0' or '\u0000' c
1b140 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 haracter or.** t
1b150 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 he nByte-th byte
1b160 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 , whichever come
1b170 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 s first. If the
1b180 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 caller knows.**
1b190 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 that the supplie
1b1a0 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d d string is nul-
1b1b0 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e terminated, then
1b1c0 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c there is a smal
1b1d0 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 l.** performance
1b1e0 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 advantage to be
1b1f0 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 gained by passi
1b200 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 ng an nByte para
1b210 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 meter that.** is
1b220 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 equal to the nu
1b230 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e mber of bytes in
1b240 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e the input strin
1b250 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f g <i>including</
1b260 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 i>.** the nul-te
1b270 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a rminator bytes..
1b280 2a 2a 0a 2a 2a 20 49 66 20 70 7a 54 61 69 6c 20 **.** If pzTail
1b290 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e is not NULL then
1b2a0 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 *pzTail is made
1b2b0 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 to point to the
1b2c0 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 first byte.** p
1b2d0 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 ast the end of t
1b2e0 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 he first SQL sta
1b2f0 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 tement in zSql.
1b300 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
1b310 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 only.** compile
1b320 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d the first statem
1b330 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 ent in zSql, so
1b340 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 *pzTail is left
1b350 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 pointing to.** w
1b360 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f hat remains unco
1b370 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 mpiled..**.** *p
1b380 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f pStmt is left po
1b390 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 inting to a comp
1b3a0 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 iled [prepared s
1b3b0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 tatement] that c
1b3c0 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 an be.** execute
1b3d0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 d using [sqlite3
1b3e0 5f 73 74 65 70 28 29 5d 2e 20 20 49 66 20 74 68 _step()]. If th
1b3f0 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c ere is an error,
1b400 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a *ppStmt is set.
1b410 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 ** to NULL. If
1b420 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 the input text c
1b430 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 ontains no SQL (
1b440 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 if the input is
1b450 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 an empty.** stri
1b460 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 ng or a comment)
1b470 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 then *ppStmt is
1b480 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a set to NULL..**
1b490 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f The calling pro
1b4a0 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e cedure is respon
1b4b0 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 sible for deleti
1b4c0 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a ng the compiled.
1b4d0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ** SQL statement
1b4e0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
1b4f0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 finalize()] afte
1b500 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 r it has finishe
1b510 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 d with it..** pp
1b520 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 Stmt may not be
1b530 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 NULL..**.** On s
1b540 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f uccess, [SQLITE_
1b550 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2c OK] is returned,
1b560 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 otherwise an [e
1b570 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 rror code] is re
1b580 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 turned..**.** Th
1b590 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 e sqlite3_prepar
1b5a0 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 e_v2() and sqlit
1b5b0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
1b5c0 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 ) interfaces are
1b5d0 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 .** recommended
1b5e0 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 for all new prog
1b5f0 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c rams. The two ol
1b600 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 der interfaces a
1b610 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 re retained.** f
1b620 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d or backwards com
1b630 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 patibility, but
1b640 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73 their use is dis
1b650 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 couraged..** In
1b660 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
1b670 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 ces, the prepare
1b680 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 d statement.** t
1b690 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 hat is returned
1b6a0 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 (the [sqlite3_st
1b6b0 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 mt] object) cont
1b6c0 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 ains a copy of t
1b6d0 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 he.** original S
1b6e0 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 QL text. This ca
1b6f0 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 uses the [sqlite
1b700 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 3_step()] interf
1b710 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 ace to.** behave
1b720 20 61 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 a differently i
1b730 6e 20 74 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a n two ways:.**.*
1b740 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a * <ol>.** <li>.*
1b750 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 * If the databas
1b760 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 e schema changes
1b770 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 , instead of ret
1b780 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 urning [SQLITE_S
1b790 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 CHEMA] as it.**
1b7a0 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 always used to d
1b7b0 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 o, [sqlite3_step
1b7c0 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 ()] will automat
1b7d0 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 ically recompile
1b7e0 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 the SQL.** stat
1b7f0 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f ement and try to
1b800 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 run it again.
1b810 49 66 20 74 68 65 20 73 63 68 65 6d 61 20 68 61 If the schema ha
1b820 73 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 s changed in.**
1b830 61 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73 a way that makes
1b840 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6e the statement n
1b850 6f 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 o longer valid,
1b860 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
1b870 20 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 will still.** r
1b880 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 eturn [SQLITE_SC
1b890 48 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 HEMA]. But unli
1b8a0 6b 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 ke the legacy be
1b8b0 68 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f havior, [SQLITE_
1b8c0 53 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f SCHEMA] is.** no
1b8d0 77 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 2e w a fatal error.
1b8e0 20 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 Calling [sqlit
1b8f0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
1b900 20 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 again will not
1b910 6d 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f make the.** erro
1b920 72 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 r go away. Note
1b930 3a 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 : use [sqlite3_e
1b940 72 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 rrmsg()] to find
1b950 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 the text.** of
1b960 74 68 65 20 70 61 72 73 69 6e 67 20 65 72 72 6f the parsing erro
1b970 72 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 69 r that results i
1b980 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 n an [SQLITE_SCH
1b990 45 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 EMA] return..**
1b9a0 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e </li>.**.** <li>
1b9b0 0a 2a 2a 20 57 68 65 6e 20 61 6e 20 65 72 72 6f .** When an erro
1b9c0 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 r occurs, [sqlit
1b9d0 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 e3_step()] will
1b9e0 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 return one of th
1b9f0 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 e detailed.** [e
1ba00 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b rror codes] or [
1ba10 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 extended error c
1ba20 6f 64 65 73 5d 2e 20 20 54 68 65 20 6c 65 67 61 odes]. The lega
1ba30 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 cy behavior was
1ba40 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 that.** [sqlite3
1ba50 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f _step()] would o
1ba60 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e nly return a gen
1ba70 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 eric [SQLITE_ERR
1ba80 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a OR] result code.
1ba90 2a 2a 20 61 6e 64 20 79 6f 75 20 77 6f 75 6c 64 ** and you would
1baa0 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 have to make a
1bab0 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b second call to [
1bac0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
1bad0 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 in order.** to
1bae0 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 find the underly
1baf0 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 ing cause of the
1bb00 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 problem. With t
1bb10 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a he "v2" prepare.
1bb20 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 ** interfaces, t
1bb30 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 he underlying re
1bb40 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 ason for the err
1bb50 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 or is returned i
1bb60 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c mmediately..** <
1bb70 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a /li>.** </ol>.**
1bb80 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
1bb90 3a 0a 2a 2a 20 5b 48 31 33 30 31 31 5d 20 5b 48 :.** [H13011] [H
1bba0 31 33 30 31 32 5d 20 5b 48 31 33 30 31 33 5d 20 13012] [H13013]
1bbb0 5b 48 31 33 30 31 34 5d 20 5b 48 31 33 30 31 35 [H13014] [H13015
1bbc0 5d 20 5b 48 31 33 30 31 36 5d 20 5b 48 31 33 30 ] [H13016] [H130
1bbd0 31 39 5d 20 5b 48 31 33 30 32 31 5d 0a 2a 2a 0a 19] [H13021].**.
1bbe0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
1bbf0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 t sqlite3_prepar
1bc00 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 e(. sqlite3 *db
1bc10 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 , /*
1bc20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 Database handle
1bc30 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
1bc40 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 *zSql, /*
1bc50 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 SQL statement, U
1bc60 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a TF-8 encoded */.
1bc70 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 int nByte,
1bc80 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 /* Max
1bc90 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a imum length of z
1bca0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f Sql in bytes. */
1bcb0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 . sqlite3_stmt
1bcc0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 **ppStmt, /* OU
1bcd0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e T: Statement han
1bce0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 dle */. const c
1bcf0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 har **pzTail
1bd00 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 /* OUT: Pointer
1bd10 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 to unused porti
1bd20 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b on of zSql */.);
1bd30 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
1bd40 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
1bd50 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 v2(. sqlite3 *d
1bd60 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a b, /*
1bd70 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 Database handle
1bd80 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
1bd90 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a *zSql, /*
1bda0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 SQL statement,
1bdb0 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f UTF-8 encoded */
1bdc0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 . int nByte,
1bdd0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 /* Ma
1bde0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 ximum length of
1bdf0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a zSql in bytes. *
1be00 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 /. sqlite3_stmt
1be10 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f **ppStmt, /* O
1be20 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 UT: Statement ha
1be30 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
1be40 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 char **pzTail
1be50 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 /* OUT: Pointe
1be60 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 r to unused port
1be70 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 ion of zSql */.)
1be80 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
1be90 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
1bea0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 16(. sqlite3 *d
1beb0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a b, /*
1bec0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 Database handle
1bed0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 */. const void
1bee0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a *zSql, /*
1bef0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 SQL statement,
1bf00 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a UTF-16 encoded *
1bf10 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 /. int nByte,
1bf20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d /* M
1bf30 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
1bf40 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 zSql in bytes.
1bf50 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d */. sqlite3_stm
1bf60 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 t **ppStmt, /*
1bf70 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 OUT: Statement h
1bf80 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
1bf90 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 void **pzTail
1bfa0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 /* OUT: Point
1bfb0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 er to unused por
1bfc0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a tion of zSql */.
1bfd0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
1bfe0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 t sqlite3_prepar
1bff0 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 e16_v2(. sqlite
1c000 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
1c010 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 /* Database ha
1c020 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
1c030 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 void *zSql,
1c040 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 /* SQL stateme
1c050 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 nt, UTF-16 encod
1c060 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 ed */. int nByt
1c070 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 e,
1c080 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 /* Maximum lengt
1c090 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 h of zSql in byt
1c0a0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 es. */. sqlite3
1c0b0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 _stmt **ppStmt,
1c0c0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 /* OUT: Stateme
1c0d0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 nt handle */. c
1c0e0 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 onst void **pzTa
1c0f0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 il /* OUT: P
1c100 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 ointer to unused
1c110 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c portion of zSql
1c120 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.);../*.** CA
1c130 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 PI3REF: Retrievi
1c140 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c ng Statement SQL
1c150 20 7b 48 31 33 31 30 30 7d 20 3c 48 31 33 30 30 {H13100} <H1300
1c160 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 0>.**.** This in
1c170 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 terface can be u
1c180 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 sed to retrieve
1c190 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 a saved copy of
1c1a0 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 the original.**
1c1b0 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f SQL text used to
1c1c0 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 create a [prepa
1c1d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 red statement] i
1c1e0 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 f that statement
1c1f0 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 was.** compiled
1c200 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 using either [s
1c210 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1c220 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 2()] or [sqlite3
1c230 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
1c240 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
1c250 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 31 30 31 ents:.** [H13101
1c260 5d 20 5b 48 31 33 31 30 32 5d 20 5b 48 31 33 31 ] [H13102] [H131
1c270 30 33 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 03].*/.SQLITE_AP
1c280 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 I const char *sq
1c290 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 lite3_sql(sqlite
1c2a0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 3_stmt *pStmt);.
1c2b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1c2c0 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 Dynamically Typ
1c2d0 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 20 ed Value Object
1c2e0 7b 48 31 35 30 30 30 7d 20 3c 53 32 30 32 30 30 {H15000} <S20200
1c2f0 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b >.** KEYWORDS: {
1c300 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
1c310 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 3_value} {unprot
1c320 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
1c330 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 lue}.**.** SQLit
1c340 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 e uses the sqlit
1c350 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 e3_value object
1c360 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c to represent all
1c370 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 values.** that
1c380 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e can be stored in
1c390 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c a database tabl
1c3a0 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 e. SQLite uses d
1c3b0 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a ynamic typing.**
1c3c0 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 for the values
1c3d0 69 74 20 73 74 6f 72 65 73 2e 20 56 61 6c 75 65 it stores. Value
1c3e0 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 s stored in sqli
1c3f0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
1c400 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 s.** can be inte
1c410 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 gers, floating p
1c420 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 oint values, str
1c430 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 ings, BLOBs, or
1c440 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 NULL..**.** An s
1c450 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
1c460 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 ect may be eithe
1c470 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 r "protected" or
1c480 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a "unprotected"..
1c490 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 ** Some interfac
1c4a0 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f es require a pro
1c4b0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
1c4c0 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 alue. Other int
1c4d0 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 erfaces.** will
1c4e0 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 accept either a
1c4f0 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 protected or an
1c500 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 unprotected sqli
1c510 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 te3_value..** Ev
1c520 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 ery interface th
1c530 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 at accepts sqlit
1c540 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e e3_value argumen
1c550 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 ts specifies.**
1c560 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 whether or not i
1c570 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f t requires a pro
1c580 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
1c590 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 alue..**.** The
1c5a0 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 terms "protected
1c5b0 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 " and "unprotect
1c5c0 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 ed" refer to whe
1c5d0 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 ther or not.** a
1c5e0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 mutex is held.
1c5f0 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 A internal mute
1c600 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 x is held for a
1c610 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c protected.** sql
1c620 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
1c630 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 t but no mutex i
1c640 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e s held for an un
1c650 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c protected.** sql
1c660 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
1c670 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 t. If SQLite is
1c680 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 compiled to be
1c690 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a single-threaded.
1c6a0 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 ** (with [SQLITE
1c6b0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 _THREADSAFE=0] a
1c6c0 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 nd with [sqlite3
1c6d0 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 _threadsafe()] r
1c6e0 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f eturning 0).** o
1c6f0 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 r if SQLite is r
1c700 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 un in one of red
1c710 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 uced mutex modes
1c720 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [SQLITE_CON
1c730 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 FIG_SINGLETHREAD
1c740 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e ] or [SQLITE_CON
1c750 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d FIG_MULTITHREAD]
1c760 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 .** then there i
1c770 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e s no distinction
1c780 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 between protect
1c790 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 ed and unprotect
1c7a0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 ed.** sqlite3_va
1c7b0 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 lue objects and
1c7c0 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 they can be used
1c7d0 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 interchangeably
1c7e0 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 . However,.** f
1c7f0 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 or maximum code
1c800 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 portability it i
1c810 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 s recommended th
1c820 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a at applications.
1c830 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 ** still make th
1c840 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 e distinction be
1c850 74 77 65 65 6e 20 62 65 74 77 65 65 6e 20 70 72 tween between pr
1c860 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 otected and unpr
1c870 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 otected.** sqlit
1c880 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
1c890 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 even when not s
1c8a0 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 trictly required
1c8b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
1c8c0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
1c8d0 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 s that are passe
1c8e0 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 d as parameters
1c8f0 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c into the.** impl
1c900 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 ementation of [a
1c910 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
1c920 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 ed SQL functions
1c930 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e ] are protected.
1c940 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
1c950 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 value object ret
1c960 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c urned by.** [sql
1c970 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 ite3_column_valu
1c980 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 e()] is unprotec
1c990 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 ted..** Unprotec
1c9a0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
1c9b0 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e e objects may on
1c9c0 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a ly be used with.
1c9d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 ** [sqlite3_resu
1c9e0 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 lt_value()] and
1c9f0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 [sqlite3_bind_va
1ca00 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b lue()]..** The [
1ca10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c sqlite3_value_bl
1ca20 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c ob | sqlite3_val
1ca30 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c ue_type()] famil
1ca40 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 y of.** interfac
1ca50 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 es require prote
1ca60 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
1ca70 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 ue objects..*/.t
1ca80 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 ypedef struct Me
1ca90 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b m sqlite3_value;
1caa0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1cab0 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 : SQL Function C
1cac0 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 20 7b 48 ontext Object {H
1cad0 31 36 30 30 31 7d 20 3c 53 32 30 32 30 30 3e 0a 16001} <S20200>.
1cae0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 **.** The contex
1caf0 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 t in which an SQ
1cb00 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 L function execu
1cb10 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e tes is stored in
1cb20 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 an.** sqlite3_c
1cb30 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 ontext object.
1cb40 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 A pointer to an
1cb50 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 sqlite3_context
1cb60 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 object.** is alw
1cb70 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 ays first parame
1cb80 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 ter to [applicat
1cb90 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 ion-defined SQL
1cba0 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 functions]..** T
1cbb0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
1cbc0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
1cbd0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ion implementati
1cbe0 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 on will pass thi
1cbf0 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 s.** pointer thr
1cc00 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 ough into calls
1cc10 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 to [sqlite3_resu
1cc20 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 lt_int | sqlite3
1cc30 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b _result()],.** [
1cc40 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
1cc50 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 e_context()], [s
1cc60 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 qlite3_user_data
1cc70 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
1cc80 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 _context_db_hand
1cc90 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f le()], [sqlite3_
1cca0 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a get_auxdata()],.
1ccb0 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 ** and/or [sqlit
1ccc0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 e3_set_auxdata()
1ccd0 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 ]..*/.typedef st
1cce0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e ruct sqlite3_con
1ccf0 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e text sqlite3_con
1cd00 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 text;../*.** CAP
1cd10 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 I3REF: Binding V
1cd20 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 alues To Prepare
1cd30 64 20 53 74 61 74 65 6d 65 6e 74 73 20 7b 48 31 d Statements {H1
1cd40 33 35 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 3500} <S70300>.*
1cd50 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 * KEYWORDS: {hos
1cd60 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f t parameter} {ho
1cd70 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b st parameters} {
1cd80 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e host parameter n
1cd90 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ame}.** KEYWORDS
1cda0 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 : {SQL parameter
1cdb0 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 } {SQL parameter
1cdc0 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 s} {parameter bi
1cdd0 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 nding}.**.** In
1cde0 74 68 65 20 53 51 4c 20 73 74 72 69 6e 67 73 20 the SQL strings
1cdf0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 input to [sqlite
1ce00 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
1ce10 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 and its variants
1ce20 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 ,.** literals ma
1ce30 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 y be replaced by
1ce40 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 a [parameter] t
1ce50 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 hat matches one
1ce60 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 of following.**
1ce70 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a templates:.**.**
1ce80 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f <ul>.** <li> ?
1ce90 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a .** <li> ?NNN.*
1cea0 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 * <li> :VVV.**
1ceb0 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c <li> @VVV.** <l
1cec0 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c i> $VVV.** </ul
1ced0 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 >.**.** In the t
1cee0 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 emplates above,
1cef0 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 NNN represents a
1cf00 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 n integer litera
1cf10 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 l,.** and VVV re
1cf20 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 presents an alph
1cf30 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 anumeric identif
1cf40 65 72 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 er. The values
1cf50 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 of these.** para
1cf60 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c meters (also cal
1cf70 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 led "host parame
1cf80 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 ter names" or "S
1cf90 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a QL parameters").
1cfa0 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 ** can be set us
1cfb0 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f ing the sqlite3_
1cfc0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 bind_*() routine
1cfd0 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a s defined here..
1cfe0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
1cff0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
1d000 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 sqlite3_bind_*()
1d010 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 routines is alw
1d020 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 ays.** a pointer
1d030 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
1d040 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 _stmt] object re
1d050 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b turned from.** [
1d060 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
1d070 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 v2()] or its var
1d080 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 iants..**.** The
1d090 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
1d0a0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 is the index of
1d0b0 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 the SQL paramet
1d0c0 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a er to be set..**
1d0d0 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 The leftmost SQ
1d0e0 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 L parameter has
1d0f0 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 an index of 1.
1d100 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 When the same na
1d110 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d med.** SQL param
1d120 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 eter is used mor
1d130 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 e than once, sec
1d140 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 ond and subseque
1d150 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 nt.** occurrence
1d160 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 s have the same
1d170 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72 index as the fir
1d180 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a st occurrence..*
1d190 2a 20 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 * The index for
1d1a0 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 named parameters
1d1b0 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 can be looked u
1d1c0 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b p using the.** [
1d1d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
1d1e0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 ameter_index()]
1d1f0 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 API if desired.
1d200 20 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f The index.** fo
1d210 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 r "?NNN" paramet
1d220 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 ers is the value
1d230 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20 of NNN..** The
1d240 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 NNN value must b
1d250 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 e between 1 and
1d260 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d the [sqlite3_lim
1d270 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 it()].** paramet
1d280 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 er [SQLITE_LIMIT
1d290 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 _VARIABLE_NUMBER
1d2a0 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 ] (default value
1d2b0 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 : 999)..**.** Th
1d2c0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 e third argument
1d2d0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f is the value to
1d2e0 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 bind to the par
1d2f0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e ameter..**.** In
1d300 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 those routines
1d310 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 that have a four
1d320 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 th argument, its
1d330 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a value is the.**
1d340 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
1d350 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 in the paramete
1d360 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a r. To be clear:
1d370 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 the value is th
1d380 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c e.** number of <
1d390 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 u>bytes</u> in t
1d3a0 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 he value, not th
1d3b0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 e number of char
1d3c0 61 63 74 65 72 73 2e 0a 2a 2a 20 49 66 20 74 68 acters..** If th
1d3d0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
1d3e0 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 er is negative,
1d3f0 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 the length of th
1d400 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 e string is.** t
1d410 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
1d420 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 es up to the fir
1d430 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 st zero terminat
1d440 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 or..**.** The fi
1d450 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 fth argument to
1d460 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
1d470 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e b(), sqlite3_bin
1d480 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a d_text(), and.**
1d490 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 sqlite3_bind_te
1d4a0 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74 xt16() is a dest
1d4b0 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 ructor used to d
1d4c0 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c ispose of the BL
1d4d0 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 OB or.** string
1d4e0 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 after SQLite has
1d4f0 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 finished with i
1d500 74 2e 20 49 66 20 74 68 65 20 66 69 66 74 68 20 t. If the fifth
1d510 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 argument is.** t
1d520 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 he special value
1d530 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d [SQLITE_STATIC]
1d540 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 , then SQLite as
1d550 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a sumes that the.*
1d560 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 * information is
1d570 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 in static, unma
1d580 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 naged space and
1d590 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f does not need to
1d5a0 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 be freed..** If
1d5b0 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d the fifth argum
1d5c0 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 ent has the valu
1d5d0 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 e [SQLITE_TRANSI
1d5e0 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 ENT], then.** SQ
1d5f0 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f Lite makes its o
1d600 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 wn private copy
1d610 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 of the data imme
1d620 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a diately, before.
1d630 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 ** the sqlite3_b
1d640 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 ind_*() routine
1d650 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 returns..**.** T
1d660 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
1d670 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 zeroblob() routi
1d680 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 ne binds a BLOB
1d690 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 of length N that
1d6a0 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 .** is filled wi
1d6b0 74 68 20 7a 65 72 6f 65 73 2e 20 20 41 20 7a 65 th zeroes. A ze
1d6c0 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 roblob uses a fi
1d6d0 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 xed amount of me
1d6e0 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e mory.** (just an
1d6f0 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 integer to hold
1d700 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 its size) while
1d710 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f it is being pro
1d720 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 cessed..** Zerob
1d730 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 lobs are intende
1d740 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c d to serve as pl
1d750 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 aceholders for B
1d760 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f LOBs whose.** co
1d770 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 ntent is later w
1d780 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 ritten using.**
1d790 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 [sqlite3_blob_op
1d7a0 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c en | incremental
1d7b0 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 BLOB I/O] routi
1d7c0 6e 65 73 2e 0a 2a 2a 20 41 20 6e 65 67 61 74 69 nes..** A negati
1d7d0 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 ve value for the
1d7e0 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 zeroblob result
1d7f0 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 s in a zero-leng
1d800 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 th BLOB..**.** T
1d810 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
1d820 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 *() routines mus
1d830 74 20 62 65 20 63 61 6c 6c 65 64 20 61 66 74 65 t be called afte
1d840 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 r.** [sqlite3_pr
1d850 65 70 61 72 65 5f 76 32 28 29 5d 20 28 61 6e 64 epare_v2()] (and
1d860 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 6f its variants) o
1d870 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 r [sqlite3_reset
1d880 28 29 5d 20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72 ()] and.** befor
1d890 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 e [sqlite3_step(
1d8a0 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20 )]..** Bindings
1d8b0 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 are not cleared
1d8c0 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f by the [sqlite3_
1d8d0 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 reset()] routine
1d8e0 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20 70 61 72 ..** Unbound par
1d8f0 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 ameters are inte
1d900 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e rpreted as NULL.
1d910 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
1d920 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 tines return [SQ
1d930 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 LITE_OK] on succ
1d940 65 73 73 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 ess or an error
1d950 63 6f 64 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68 code if.** anyth
1d960 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20 ing goes wrong.
1d970 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 [SQLITE_RANGE]
1d980 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 is returned if t
1d990 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 he parameter.**
1d9a0 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 index is out of
1d9b0 72 61 6e 67 65 2e 20 20 5b 53 51 4c 49 54 45 5f range. [SQLITE_
1d9c0 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e NOMEM] is return
1d9d0 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 ed if malloc() f
1d9e0 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45 ails..** [SQLITE
1d9f0 5f 4d 49 53 55 53 45 5d 20 6d 69 67 68 74 20 62 _MISUSE] might b
1da00 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 e returned if th
1da10 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
1da20 20 63 61 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20 called on a.**
1da30 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 virtual machine
1da40 74 68 61 74 20 69 73 20 74 68 65 20 77 72 6f 6e that is the wron
1da50 67 20 73 74 61 74 65 20 6f 72 20 77 68 69 63 68 g state or which
1da60 20 68 61 73 20 61 6c 72 65 61 64 79 20 62 65 65 has already bee
1da70 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 n finalized..**
1da80 44 65 74 65 63 74 69 6f 6e 20 6f 66 20 6d 69 73 Detection of mis
1da90 75 73 65 20 69 73 20 75 6e 72 65 6c 69 61 62 6c use is unreliabl
1daa0 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 e. Applications
1dab0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 64 65 70 65 should not depe
1dac0 6e 64 0a 2a 2a 20 6f 6e 20 53 51 4c 49 54 45 5f nd.** on SQLITE_
1dad0 4d 49 53 55 53 45 20 72 65 74 75 72 6e 73 2e 20 MISUSE returns.
1dae0 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 69 SQLITE_MISUSE i
1daf0 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 69 6e s intended to in
1db00 64 69 63 61 74 65 20 61 0a 2a 2a 20 61 20 6c 6f dicate a.** a lo
1db10 67 69 63 20 65 72 72 6f 72 20 69 6e 20 74 68 65 gic error in the
1db20 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 46 application. F
1db30 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f uture versions o
1db40 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a f SQLite might.*
1db50 2a 20 70 61 6e 69 63 20 72 61 74 68 65 72 20 74 * panic rather t
1db60 68 61 6e 20 72 65 74 75 72 6e 20 53 51 4c 49 54 han return SQLIT
1db70 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 E_MISUSE..**.**
1db80 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 See also: [sqlit
1db90 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
1dba0 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b r_count()],.** [
1dbb0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
1dbc0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 ameter_name()],
1dbd0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e and [sqlite3_bin
1dbe0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 d_parameter_inde
1dbf0 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 x()]..**.** Requ
1dc00 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
1dc10 33 35 30 36 5d 20 5b 48 31 33 35 30 39 5d 20 5b 3506] [H13509] [
1dc20 48 31 33 35 31 32 5d 20 5b 48 31 33 35 31 35 5d H13512] [H13515]
1dc30 20 5b 48 31 33 35 31 38 5d 20 5b 48 31 33 35 32 [H13518] [H1352
1dc40 31 5d 20 5b 48 31 33 35 32 34 5d 20 5b 48 31 33 1] [H13524] [H13
1dc50 35 32 37 5d 0a 2a 2a 20 5b 48 31 33 35 33 30 5d 527].** [H13530]
1dc60 20 5b 48 31 33 35 33 33 5d 20 5b 48 31 33 35 33 [H13533] [H1353
1dc70 36 5d 20 5b 48 31 33 35 33 39 5d 20 5b 48 31 33 6] [H13539] [H13
1dc80 35 34 32 5d 20 5b 48 31 33 35 34 35 5d 20 5b 48 542] [H13545] [H
1dc90 31 33 35 34 38 5d 20 5b 48 31 33 35 35 31 5d 0a 13548] [H13551].
1dca0 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 **.*/.SQLITE_API
1dcb0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e int sqlite3_bin
1dcc0 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 d_blob(sqlite3_s
1dcd0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 tmt*, int, const
1dce0 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 void*, int n, v
1dcf0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
1dd00 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
1dd10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 qlite3_bind_doub
1dd20 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a le(sqlite3_stmt*
1dd30 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a , int, double);.
1dd40 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
1dd50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 qlite3_bind_int(
1dd60 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
1dd70 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 nt, int);.SQLITE
1dd80 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
1dd90 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 _bind_int64(sqli
1dda0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
1ddb0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a sqlite3_int64);.
1ddc0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
1ddd0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c qlite3_bind_null
1dde0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
1ddf0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 int);.SQLITE_API
1de00 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e int sqlite3_bin
1de10 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 d_text(sqlite3_s
1de20 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 tmt*, int, const
1de30 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 char*, int n, v
1de40 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
1de50 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
1de60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
1de70 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
1de80 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 , int, const voi
1de90 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 d*, int, void(*)
1dea0 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 (void*));.SQLITE
1deb0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
1dec0 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 _bind_value(sqli
1ded0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
1dee0 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 const sqlite3_va
1def0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 lue*);.SQLITE_AP
1df00 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 I int sqlite3_bi
1df10 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 nd_zeroblob(sqli
1df20 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
1df30 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 int n);../*.** C
1df40 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 API3REF: Number
1df50 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 Of SQL Parameter
1df60 73 20 7b 48 31 33 36 30 30 7d 20 3c 53 37 30 33 s {H13600} <S703
1df70 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 00>.**.** This r
1df80 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 outine can be us
1df90 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e ed to find the n
1dfa0 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 umber of [SQL pa
1dfb0 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 rameters].** in
1dfc0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
1dfd0 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 ement]. SQL par
1dfe0 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 ameters are toke
1dff0 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 ns of the.** for
1e000 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 m "?", "?NNN", "
1e010 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f :AAA", "$AAA", o
1e020 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 r "@AAA" that se
1e030 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 rve as.** placeh
1e040 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 olders for value
1e050 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 s that are [sqli
1e060 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 te3_bind_blob |
1e070 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 bound].** to the
1e080 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 parameters at a
1e090 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a later time..**.
1e0a0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
1e0b0 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 actually returns
1e0c0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 the index of th
1e0d0 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 e largest (right
1e0e0 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 most).** paramet
1e0f0 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d er. For all form
1e100 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 s except ?NNN, t
1e110 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 his will corresp
1e120 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 ond to the.** nu
1e130 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 mber of unique p
1e140 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 arameters. If p
1e150 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 arameters of the
1e160 20 3f 4e 4e 4e 20 61 72 65 20 75 73 65 64 2c 0a ?NNN are used,.
1e170 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 ** there may be
1e180 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 gaps in the list
1e190 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
1e1a0 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f : [sqlite3_bind_
1e1b0 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e blob|sqlite3_bin
1e1c0 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 d()],.** [sqlite
1e1d0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
1e1e0 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a _name()], and.**
1e1f0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
1e200 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 arameter_index()
1e210 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 ]..**.** Require
1e220 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 30 ments:.** [H1360
1e230 31 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 1].*/.SQLITE_API
1e240 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e int sqlite3_bin
1e250 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e d_parameter_coun
1e260 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 t(sqlite3_stmt*)
1e270 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1e280 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 F: Name Of A Hos
1e290 74 20 50 61 72 61 6d 65 74 65 72 20 7b 48 31 33 t Parameter {H13
1e2a0 36 32 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 620} <S70300>.**
1e2b0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
1e2c0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
1e2d0 65 72 20 74 6f 20 74 68 65 20 6e 61 6d 65 20 6f er to the name o
1e2e0 66 20 74 68 65 20 6e 2d 74 68 0a 2a 2a 20 5b 53 f the n-th.** [S
1e2f0 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e QL parameter] in
1e300 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
1e310 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20 tement]..** SQL
1e320 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 parameters of th
1e330 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 e form "?NNN" or
1e340 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 ":AAA" or "@AAA
1e350 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 " or "$AAA".** h
1e360 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 ave a name which
1e370 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 is the string "
1e380 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 ?NNN" or ":AAA"
1e390 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 or "@AAA" or "$A
1e3a0 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 AA".** respectiv
1e3b0 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 ely..** In other
1e3c0 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 words, the init
1e3d0 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f ial ":" or "$" o
1e3e0 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 r "@" or "?".**
1e3f0 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 is included as p
1e400 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e art of the name.
1e410 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 73 20 6f .** Parameters o
1e420 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 f the form "?" w
1e430 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 ithout a followi
1e440 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 ng integer have
1e450 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 no name.** and a
1e460 72 65 20 61 6c 73 6f 20 72 65 66 65 72 72 65 64 re also referred
1e470 20 74 6f 20 61 73 20 22 61 6e 6f 6e 79 6d 6f 75 to as "anonymou
1e480 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a s parameters"..*
1e490 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 68 *.** The first h
1e4a0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 ost parameter ha
1e4b0 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c s an index of 1,
1e4c0 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 not 0..**.** If
1e4d0 20 74 68 65 20 76 61 6c 75 65 20 6e 20 69 73 20 the value n is
1e4e0 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 out of range or
1e4f0 69 66 20 74 68 65 20 6e 2d 74 68 20 70 61 72 61 if the n-th para
1e500 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 meter is.** name
1e510 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 less, then NULL
1e520 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 is returned. Th
1e530 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e e returned strin
1e540 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 g is.** always i
1e550 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 n UTF-8 encoding
1e560 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d even if the nam
1e570 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 ed parameter was
1e580 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 .** originally s
1e590 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d pecified as UTF-
1e5a0 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 16 in [sqlite3_p
1e5b0 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a repare16()] or.*
1e5c0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
1e5d0 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a re16_v2()]..**.*
1e5e0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
1e5f0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 ite3_bind_blob|s
1e600 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a qlite3_bind()],.
1e610 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
1e620 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 _parameter_count
1e630 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ()], and.** [sql
1e640 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
1e650 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a ter_index()]..**
1e660 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
1e670 3a 0a 2a 2a 20 5b 48 31 33 36 32 31 5d 0a 2a 2f :.** [H13621].*/
1e680 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
1e690 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
1e6a0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e bind_parameter_n
1e6b0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ame(sqlite3_stmt
1e6c0 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *, int);../*.**
1e6d0 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 CAPI3REF: Index
1e6e0 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 Of A Parameter W
1e6f0 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 ith A Given Name
1e700 20 7b 48 31 33 36 34 30 7d 20 3c 53 37 30 33 30 {H13640} <S7030
1e710 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 0>.**.** Return
1e720 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 the index of an
1e730 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 SQL parameter gi
1e740 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 54 ven its name. T
1e750 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 he.** index valu
1e760 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 e returned is su
1e770 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 itable for use a
1e780 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 s the second.**
1e790 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 parameter to [sq
1e7a0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c lite3_bind_blob|
1e7b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e sqlite3_bind()].
1e7c0 20 20 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 A zero.** is r
1e7d0 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 eturned if no ma
1e7e0 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 tching parameter
1e7f0 20 69 73 20 66 6f 75 6e 64 2e 20 20 54 68 65 20 is found. The
1e800 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d parameter.** nam
1e810 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 e must be given
1e820 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 in UTF-8 even if
1e830 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 the original st
1e840 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 atement.** was p
1e850 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 repared from UTF
1e860 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b -16 text using [
1e870 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
1e880 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 6_v2()]..**.** S
1e890 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
1e8a0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 3_bind_blob|sqli
1e8b0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 te3_bind()],.**
1e8c0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
1e8d0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d rameter_count()]
1e8e0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 , and.** [sqlite
1e8f0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
1e900 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a _index()]..**.**
1e910 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
1e920 2a 20 5b 48 31 33 36 34 31 5d 0a 2a 2f 0a 53 51 * [H13641].*/.SQ
1e930 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
1e940 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
1e950 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 ter_index(sqlite
1e960 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 3_stmt*, const c
1e970 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a har *zName);../*
1e980 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 .** CAPI3REF: Re
1e990 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 set All Bindings
1e9a0 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 On A Prepared S
1e9b0 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 36 36 30 tatement {H13660
1e9c0 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a } <S70300>.**.**
1e9d0 20 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 Contrary to the
1e9e0 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 intuition of ma
1e9f0 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 ny, [sqlite3_res
1ea00 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 et()] does not r
1ea10 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c eset.** the [sql
1ea20 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c ite3_bind_blob |
1ea30 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 bindings] on a
1ea40 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
1ea50 65 6e 74 5d 2e 0a 2a 2a 20 55 73 65 20 74 68 69 ent]..** Use thi
1ea60 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 s routine to res
1ea70 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 et all host para
1ea80 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a meters to NULL..
1ea90 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
1eaa0 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 36 31 5d 0a ts:.** [H13661].
1eab0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
1eac0 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f t sqlite3_clear_
1ead0 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 bindings(sqlite3
1eae0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 _stmt*);../*.**
1eaf0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 CAPI3REF: Number
1eb00 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 Of Columns In A
1eb10 20 52 65 73 75 6c 74 20 53 65 74 20 7b 48 31 33 Result Set {H13
1eb20 37 31 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 710} <S10700>.**
1eb30 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 6e .** Return the n
1eb40 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
1eb50 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 in the result s
1eb60 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 et returned by t
1eb70 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 he.** [prepared
1eb80 73 74 61 74 65 6d 65 6e 74 5d 2e 20 54 68 69 73 statement]. This
1eb90 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
1eba0 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 0 if pStmt is a
1ebb0 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 n SQL.** stateme
1ebc0 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 nt that does not
1ebd0 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f return data (fo
1ebe0 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 r example an [UP
1ebf0 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 52 65 DATE])..**.** Re
1ec00 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
1ec10 48 31 33 37 31 31 5d 0a 2a 2f 0a 53 51 4c 49 54 H13711].*/.SQLIT
1ec20 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
1ec30 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 3_column_count(s
1ec40 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
1ec50 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
1ec60 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 3REF: Column Nam
1ec70 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 es In A Result S
1ec80 65 74 20 7b 48 31 33 37 32 30 7d 20 3c 53 31 30 et {H13720} <S10
1ec90 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 700>.**.** These
1eca0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
1ecb0 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e the name assign
1ecc0 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c ed to a particul
1ecd0 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 ar column.** in
1ece0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f the result set o
1ecf0 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 f a [SELECT] sta
1ed00 74 65 6d 65 6e 74 2e 20 20 54 68 65 20 73 71 6c tement. The sql
1ed10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
1ed20 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 ().** interface
1ed30 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
1ed40 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d r to a zero-term
1ed50 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 inated UTF-8 str
1ed60 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 ing.** and sqlit
1ed70 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 e3_column_name16
1ed80 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 () returns a poi
1ed90 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 nter to a zero-t
1eda0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 erminated.** UTF
1edb0 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65 -16 string. The
1edc0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
1edd0 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 is the [prepare
1ede0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 d statement].**
1edf0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 that implements
1ee00 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 the [SELECT] sta
1ee10 74 65 6d 65 6e 74 2e 20 54 68 65 20 73 65 63 6f tement. The seco
1ee20 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
1ee30 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 the.** column nu
1ee40 6d 62 65 72 2e 20 20 54 68 65 20 6c 65 66 74 6d mber. The leftm
1ee50 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 ost column is nu
1ee60 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 mber 0..**.** Th
1ee70 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e e returned strin
1ee80 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c g pointer is val
1ee90 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 id until either
1eea0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
1eeb0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 atement].** is d
1eec0 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c estroyed by [sql
1eed0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
1eee0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 or until the ne
1eef0 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 xt call to.** sq
1ef00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d lite3_column_nam
1ef10 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 e() or sqlite3_c
1ef20 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f olumn_name16() o
1ef30 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d n the same colum
1ef40 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 n..**.** If sqli
1ef50 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 te3_malloc() fai
1ef60 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 ls during the pr
1ef70 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 ocessing of eith
1ef80 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 er routine.** (f
1ef90 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e or example durin
1efa0 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 g a conversion f
1efb0 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 rom UTF-8 to UTF
1efc0 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e -16) then a.** N
1efd0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 ULL pointer is r
1efe0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 eturned..**.** T
1eff0 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 he name of a res
1f000 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 ult column is th
1f010 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 e value of the "
1f020 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a AS" clause for.*
1f030 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 * that column, i
1f040 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 f there is an AS
1f050 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 clause. If the
1f060 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 re is no AS clau
1f070 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e se.** then the n
1f080 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d ame of the colum
1f090 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 n is unspecified
1f0a0 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 and may change
1f0b0 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 from.** one rele
1f0c0 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f ase of SQLite to
1f0d0 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a the next..**.**
1f0e0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
1f0f0 2a 20 5b 48 31 33 37 32 31 5d 20 5b 48 31 33 37 * [H13721] [H137
1f100 32 33 5d 20 5b 48 31 33 37 32 34 5d 20 5b 48 31 23] [H13724] [H1
1f110 33 37 32 35 5d 20 5b 48 31 33 37 32 36 5d 20 5b 3725] [H13726] [
1f120 48 31 33 37 32 37 5d 0a 2a 2f 0a 53 51 4c 49 54 H13727].*/.SQLIT
1f130 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 E_API const char
1f140 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
1f150 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 _name(sqlite3_st
1f160 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c mt*, int N);.SQL
1f170 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f ITE_API const vo
1f180 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 id *sqlite3_colu
1f190 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 mn_name16(sqlite
1f1a0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 3_stmt*, int N);
1f1b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1f1c0 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 : Source Of Data
1f1d0 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 In A Query Resu
1f1e0 6c 74 20 7b 48 31 33 37 34 30 7d 20 3c 53 31 30 lt {H13740} <S10
1f1f0 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 700>.**.** These
1f200 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 routines provid
1f210 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 e a means to det
1f220 65 72 6d 69 6e 65 20 77 68 61 74 20 63 6f 6c 75 ermine what colu
1f230 6d 6e 20 6f 66 20 77 68 61 74 0a 2a 2a 20 74 61 mn of what.** ta
1f240 62 6c 65 20 69 6e 20 77 68 69 63 68 20 64 61 74 ble in which dat
1f250 61 62 61 73 65 20 61 20 72 65 73 75 6c 74 20 6f abase a result o
1f260 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 f a [SELECT] sta
1f270 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f tement comes fro
1f280 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f m..** The name o
1f290 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f f the database o
1f2a0 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d r table or colum
1f2b0 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 n can be returne
1f2c0 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 d as.** either a
1f2d0 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 UTF-8 or UTF-16
1f2e0 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 string. The _d
1f2f0 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 atabase_ routine
1f300 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 s return.** the
1f310 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 database name, t
1f320 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 he _table_ routi
1f330 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 nes return the t
1f340 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a able name, and.*
1f350 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f * the origin_ ro
1f360 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 utines return th
1f370 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a e column name..*
1f380 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 * The returned s
1f390 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 tring is valid u
1f3a0 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 ntil the [prepar
1f3b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 ed statement] is
1f3c0 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 destroyed.** us
1f3d0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e ing [sqlite3_fin
1f3e0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 alize()] or unti
1f3f0 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 l the same infor
1f400 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 mation is reques
1f410 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 ted.** again in
1f420 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f a different enco
1f430 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ding..**.** The
1f440 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 names returned a
1f450 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 re the original
1f460 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 un-aliased names
1f470 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 of the.** datab
1f480 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 ase, table, and
1f490 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 column..**.** Th
1f4a0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
1f4b0 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e to the followin
1f4c0 67 20 63 61 6c 6c 73 20 69 73 20 61 20 5b 70 72 g calls is a [pr
1f4d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1f4e0 5d 2e 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 ]..** These func
1f4f0 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 tions return inf
1f500 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 ormation about t
1f510 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 he Nth column re
1f520 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 turned by.** the
1f530 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 statement, wher
1f540 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e e N is the secon
1f550 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d d function argum
1f560 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ent..**.** If th
1f570 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 e Nth column ret
1f580 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 urned by the sta
1f590 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 tement is an exp
1f5a0 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 ression or.** su
1f5b0 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f bquery and is no
1f5c0 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 t a column value
1f5d0 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 , then all of th
1f5e0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 ese functions re
1f5f0 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 54 turn.** NULL. T
1f600 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 hese routine mig
1f610 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e ht also return N
1f620 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 ULL if a memory
1f630 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 allocation error
1f640 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 4f 74 68 .** occurs. Oth
1f650 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 erwise, they ret
1f660 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 urn the name of
1f670 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 the attached dat
1f680 61 62 61 73 65 2c 20 74 61 62 6c 65 0a 2a 2a 20 abase, table.**
1f690 61 6e 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 and column that
1f6a0 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c query result col
1f6b0 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 umn was extracte
1f6c0 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 d from..**.** As
1f6d0 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 with all other
1f6e0 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f SQLite APIs, tho
1f6f0 73 65 20 70 6f 73 74 66 69 78 65 64 20 77 69 74 se postfixed wit
1f700 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a h "16" return.**
1f710 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 UTF-16 encoded
1f720 73 74 72 69 6e 67 73 2c 20 74 68 65 20 6f 74 68 strings, the oth
1f730 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 er functions ret
1f740 75 72 6e 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d urn UTF-8. {END}
1f750 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50 49 .**.** These API
1f760 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c s are only avail
1f770 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 able if the libr
1f780 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 ary was compiled
1f790 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 with the.** [SQ
1f7a0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 LITE_ENABLE_COLU
1f7b0 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 MN_METADATA] C-p
1f7c0 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 reprocessor symb
1f7d0 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a ol defined..**.*
1f7e0 2a 20 7b 41 31 33 37 35 31 7d 0a 2a 2a 20 49 66 * {A13751}.** If
1f7f0 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 two or more thr
1f800 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 eads call one or
1f810 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 more of these r
1f820 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 outines against
1f830 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 the same.** prep
1f840 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 ared statement a
1f850 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 nd column at the
1f860 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 same time then
1f870 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a the results are.
1f880 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a ** undefined..**
1f890 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
1f8a0 3a 0a 2a 2a 20 5b 48 31 33 37 34 31 5d 20 5b 48 :.** [H13741] [H
1f8b0 31 33 37 34 32 5d 20 5b 48 31 33 37 34 33 5d 20 13742] [H13743]
1f8c0 5b 48 31 33 37 34 34 5d 20 5b 48 31 33 37 34 35 [H13744] [H13745
1f8d0 5d 20 5b 48 31 33 37 34 36 5d 20 5b 48 31 33 37 ] [H13746] [H137
1f8e0 34 38 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 48].**.** If two
1f8f0 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 or more threads
1f900 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 call one or mor
1f910 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f e.** [sqlite3_co
1f920 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 lumn_database_na
1f930 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 me | column meta
1f940 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d data interfaces]
1f950 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 .** for the same
1f960 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
1f970 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 ment] and result
1f980 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 column.** at th
1f990 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e e same time then
1f9a0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 the results are
1f9b0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 undefined..*/.S
1f9c0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
1f9d0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
1f9e0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 lumn_database_na
1f9f0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
1fa00 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 ,int);.SQLITE_AP
1fa10 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 I const void *sq
1fa20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 lite3_column_dat
1fa30 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c abase_name16(sql
1fa40 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
1fa50 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
1fa60 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
1fa70 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d column_table_nam
1fa80 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
1fa90 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 int);.SQLITE_API
1faa0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c const void *sql
1fab0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c ite3_column_tabl
1fac0 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 e_name16(sqlite3
1fad0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c _stmt*,int);.SQL
1fae0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 ITE_API const ch
1faf0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ar *sqlite3_colu
1fb00 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 mn_origin_name(s
1fb10 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
1fb20 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
1fb30 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
1fb40 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 3_column_origin_
1fb50 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 name16(sqlite3_s
1fb60 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a tmt*,int);../*.*
1fb70 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c * CAPI3REF: Decl
1fb80 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 ared Datatype Of
1fb90 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 A Query Result
1fba0 7b 48 31 33 37 36 30 7d 20 3c 53 31 30 37 30 30 {H13760} <S10700
1fbb0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 >.**.** The firs
1fbc0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 t parameter is a
1fbd0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
1fbe0 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 ment]..** If thi
1fbf0 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 s statement is a
1fc00 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d [SELECT] statem
1fc10 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 ent and the Nth
1fc20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a column of the.**
1fc30 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 returned result
1fc40 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 set of that [SE
1fc50 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 LECT] is a table
1fc60 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a column (not an.
1fc70 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 ** expression or
1fc80 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 subquery) then
1fc90 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 the declared typ
1fca0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a e of the table.*
1fcb0 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 * column is retu
1fcc0 72 6e 65 64 2e 20 20 49 66 20 74 68 65 20 4e 74 rned. If the Nt
1fcd0 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 h column of the
1fce0 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e result set is an
1fcf0 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f .** expression o
1fd00 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e r subquery, then
1fd10 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
1fd20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 is returned..**
1fd30 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 The returned str
1fd40 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 ing is always UT
1fd50 46 2d 38 20 65 6e 63 6f 64 65 64 2e 20 7b 45 4e F-8 encoded. {EN
1fd60 44 7d 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 D}.**.** For exa
1fd70 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 mple, given the
1fd80 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a database schema:
1fd90 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 .**.** CREATE TA
1fda0 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e BLE t1(c1 VARIAN
1fdb0 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 T);.**.** and th
1fdc0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 e following stat
1fdd0 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 ement to be comp
1fde0 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 iled:.**.** SELE
1fdf0 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 CT c1 + 1, c1 FR
1fe00 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 OM t1;.**.** thi
1fe10 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 s routine would
1fe20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e return the strin
1fe30 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 g "VARIANT" for
1fe40 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c the second resul
1fe50 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d t.** column (i==
1fe60 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 1), and a NULL p
1fe70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 ointer for the f
1fe80 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 irst result colu
1fe90 6d 6e 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a mn (i==0)..**.**
1fea0 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e SQLite uses dyn
1feb0 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 amic run-time ty
1fec0 70 69 6e 67 2e 20 20 53 6f 20 6a 75 73 74 20 62 ping. So just b
1fed0 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a ecause a column.
1fee0 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 ** is declared t
1fef0 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 o contain a part
1ff00 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 icular type does
1ff10 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 not mean that t
1ff20 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 he.** data store
1ff30 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e d in that column
1ff40 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 is of the decla
1ff50 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 red type. SQLit
1ff60 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 e is.** strongly
1ff70 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 typed, but the
1ff80 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 typing is dynami
1ff90 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 54 c not static. T
1ffa0 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 ype.** is associ
1ffb0 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 ated with indivi
1ffc0 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 dual values, not
1ffd0 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 with the contai
1ffe0 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 ners.** used to
1fff0 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 hold those value
20000 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 s..**.** Require
20010 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 36 ments:.** [H1376
20020 31 5d 20 5b 48 31 33 37 36 32 5d 20 5b 48 31 33 1] [H13762] [H13
20030 37 36 33 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 763].*/.SQLITE_A
20040 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 PI const char *s
20050 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 qlite3_column_de
20060 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 cltype(sqlite3_s
20070 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 tmt*,int);.SQLIT
20080 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 E_API const void
20090 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
200a0 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 _decltype16(sqli
200b0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
200c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
200d0 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c Evaluate An SQL
200e0 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 32 Statement {H132
200f0 30 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 00} <S10000>.**.
20100 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 ** After a [prep
20110 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
20120 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 has been prepare
20130 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a d using either.*
20140 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
20150 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c re_v2()] or [sql
20160 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
20170 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 2()] or one of t
20180 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 he legacy.** int
20190 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 erfaces [sqlite3
201a0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b _prepare()] or [
201b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
201c0 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 6()], this funct
201d0 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 ion.** must be c
201e0 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 alled one or mor
201f0 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 e times to evalu
20200 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e ate the statemen
20210 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 t..**.** The det
20220 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 ails of the beha
20230 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 vior of the sqli
20240 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 te3_step() inter
20250 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f face depend.** o
20260 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 n whether the st
20270 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 atement was prep
20280 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e ared using the n
20290 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 ewer "v2" interf
202a0 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ace.** [sqlite3_
202b0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e prepare_v2()] an
202c0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 d [sqlite3_prepa
202d0 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 re16_v2()] or th
202e0 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a e older legacy.*
202f0 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c * interface [sql
20300 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
20310 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 and [sqlite3_pre
20320 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 pare16()]. The
20330 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 use of the.** ne
20340 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 w "v2" interface
20350 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 is recommended
20360 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 for new applicat
20370 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 ions but the leg
20380 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 acy.** interface
20390 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 will continue t
203a0 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a o be supported..
203b0 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65 67 **.** In the leg
203c0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 acy interface, t
203d0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
203e0 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b will be either [
203f0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a SQLITE_BUSY],.**
20400 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 [SQLITE_DONE],
20410 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 [SQLITE_ROW], [S
20420 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 QLITE_ERROR], or
20430 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
20440 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 22 76 ..** With the "v
20450 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 2" interface, an
20460 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b y of the other [
20470 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 result codes] or
20480 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 .** [extended re
20490 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 sult codes] migh
204a0 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 t be returned as
204b0 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 well..**.** [SQ
204c0 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 LITE_BUSY] means
204d0 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 that the databa
204e0 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e se engine was un
204f0 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 able to acquire
20500 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 the.** database
20510 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 locks it needs t
20520 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 49 o do its job. I
20530 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 f the statement
20540 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a is a [COMMIT].**
20550 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 or occurs outsi
20560 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 de of an explici
20570 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 t transaction, t
20580 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 hen you can retr
20590 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 y the.** stateme
205a0 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 nt. If the stat
205b0 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b ement is not a [
205c0 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 COMMIT] and occu
205d0 72 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 rs within a.** e
205e0 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 xplicit transact
205f0 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f ion then you sho
20600 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 uld rollback the
20610 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 transaction bef
20620 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e ore.** continuin
20630 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 g..**.** [SQLITE
20640 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 _DONE] means tha
20650 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 t the statement
20660 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 has finished exe
20670 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 cuting.** succes
20680 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 sfully. sqlite3
20690 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e _step() should n
206a0 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 ot be called aga
206b0 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 in on this virtu
206c0 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 al.** machine wi
206d0 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c thout first call
206e0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 ing [sqlite3_res
206f0 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 et()] to reset t
20700 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 he virtual.** ma
20710 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 chine back to it
20720 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e s initial state.
20730 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 .**.** If the SQ
20740 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e L statement bein
20750 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 g executed retur
20760 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 ns any data, the
20770 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a n [SQLITE_ROW].*
20780 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 * is returned ea
20790 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f ch time a new ro
207a0 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 w of data is rea
207b0 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e dy for processin
207c0 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c g by the.** call
207d0 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d er. The values m
207e0 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75 ay be accessed u
207f0 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e sing the [column
20800 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e access function
20810 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 s]..** sqlite3_s
20820 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 tep() is called
20830 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 again to retriev
20840 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f e the next row o
20850 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5b 53 f data..**.** [S
20860 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 QLITE_ERROR] mea
20870 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 ns that a run-ti
20880 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 me error (such a
20890 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a s a constraint.*
208a0 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 * violation) has
208b0 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 occurred. sqli
208c0 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c te3_step() shoul
208d0 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 d not be called
208e0 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 again on.** the
208f0 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 VM. More informa
20900 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e tion may be foun
20910 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 d by calling [sq
20920 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e lite3_errmsg()].
20930 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 6c 65 67 .** With the leg
20940 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 acy interface, a
20950 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 more specific e
20960 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 rror code (for e
20970 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 xample,.** [SQLI
20980 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b TE_INTERRUPT], [
20990 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 SQLITE_SCHEMA],
209a0 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d [SQLITE_CORRUPT]
209b0 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a , and so forth).
209c0 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e ** can be obtain
209d0 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 ed by calling [s
209e0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
209f0 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 on the.** [prepa
20a00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 red statement].
20a10 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 In the "v2" int
20a20 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d erface,.** the m
20a30 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 ore specific err
20a40 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 or code is retur
20a50 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 ned directly by
20a60 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a sqlite3_step()..
20a70 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 **.** [SQLITE_MI
20a80 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 SUSE] means that
20a90 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e the this routin
20aa0 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 e was called ina
20ab0 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a ppropriately..**
20ac0 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 Perhaps it was
20ad0 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 called on a [pre
20ae0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
20af0 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 that has.** alr
20b00 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 eady been [sqlit
20b10 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 e3_finalize | fi
20b20 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f nalized] or on o
20b30 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 ne that had.** p
20b40 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e reviously return
20b50 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 ed [SQLITE_ERROR
20b60 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e ] or [SQLITE_DON
20b70 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 E]. Or it could
20b80 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 .** be the case
20b90 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 that the same da
20ba0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
20bb0 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 n is being used
20bc0 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 by two or.** mor
20bd0 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 e threads at the
20be0 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 same moment in
20bf0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 time..**.** <b>G
20c00 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 oofy Interface A
20c10 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 lert:</b> In the
20c20 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 legacy interfac
20c30 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 e, the sqlite3_s
20c40 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 tep().** API alw
20c50 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 ays returns a ge
20c60 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 neric error code
20c70 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d , [SQLITE_ERROR]
20c80 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a , following any.
20c90 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 ** error other t
20ca0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 han [SQLITE_BUSY
20cb0 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 ] and [SQLITE_MI
20cc0 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 SUSE]. You must
20cd0 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 call.** [sqlite
20ce0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 3_reset()] or [s
20cf0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
20d00 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 )] in order to f
20d10 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a ind one of the.*
20d20 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f * specific [erro
20d30 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 r codes] that be
20d40 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 tter describes t
20d50 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 he error..** We
20d60 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 admit that this
20d70 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 is a goofy desig
20d80 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 n. The problem
20d90 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a has been fixed.*
20da0 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 * with the "v2"
20db0 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 interface. If y
20dc0 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f ou prepare all o
20dd0 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 f your SQL state
20de0 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 ments.** using e
20df0 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 ither [sqlite3_p
20e00 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
20e10 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
20e20 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 16_v2()] instead
20e30 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 .** of the legac
20e40 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 y [sqlite3_prepa
20e50 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 re()] and [sqlit
20e60 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 e3_prepare16()]
20e70 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 interfaces,.** t
20e80 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 hen the more spe
20e90 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 cific [error cod
20ea0 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 es] are returned
20eb0 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 directly.** by
20ec0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 sqlite3_step().
20ed0 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 The use of the
20ee0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 "v2" interface i
20ef0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a s recommended..*
20f00 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
20f10 73 3a 0a 2a 2a 20 5b 48 31 33 32 30 32 5d 20 5b s:.** [H13202] [
20f20 48 31 35 33 30 34 5d 20 5b 48 31 35 33 30 36 5d H15304] [H15306]
20f30 20 5b 48 31 35 33 30 38 5d 20 5b 48 31 35 33 31 [H15308] [H1531
20f40 30 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 0].*/.SQLITE_API
20f50 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 int sqlite3_ste
20f60 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 p(sqlite3_stmt*)
20f70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
20f80 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c F: Number of col
20f90 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 umns in a result
20fa0 20 73 65 74 20 7b 48 31 33 37 37 30 7d 20 3c 53 set {H13770} <S
20fb0 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 10700>.**.** Ret
20fc0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
20fd0 6f 66 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65 of values in the
20fe0 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 current row of
20ff0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 2e 0a the result set..
21000 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
21010 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 37 31 5d 20 ts:.** [H13771]
21020 5b 48 31 33 37 37 32 5d 0a 2a 2f 0a 53 51 4c 49 [H13772].*/.SQLI
21030 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
21040 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 e3_data_count(sq
21050 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d lite3_stmt *pStm
21060 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
21070 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c REF: Fundamental
21080 20 44 61 74 61 74 79 70 65 73 20 7b 48 31 30 32 Datatypes {H102
21090 36 35 7d 20 3c 53 31 30 31 31 30 3e 3c 53 31 30 65} <S10110><S10
210a0 31 32 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 120>.** KEYWORDS
210b0 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a : SQLITE_TEXT.**
210c0 0a 2a 2a 20 7b 48 31 30 32 36 36 7d 20 45 76 65 .** {H10266} Eve
210d0 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 ry value in SQLi
210e0 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 te has one of fi
210f0 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 ve fundamental d
21100 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 atatypes:.**.**
21110 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d <ul>.** <li> 64-
21120 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 bit signed integ
21130 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 er.** <li> 64-bi
21140 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 t IEEE floating
21150 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 point number.**
21160 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c <li> string.** <
21170 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e li> BLOB.** <li>
21180 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b NULL.** </ul> {
21190 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 END}.**.** These
211a0 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 constants are c
211b0 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 odes for each of
211c0 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a those types..**
211d0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 .** Note that th
211e0 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f e SQLITE_TEXT co
211f0 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 nstant was also
21200 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 used in SQLite v
21210 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 ersion 2.** for
21220 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 a completely dif
21230 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 ferent meaning.
21240 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c Software that l
21250 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 inks against bot
21260 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 h.** SQLite vers
21270 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 ion 2 and SQLite
21280 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c version 3 shoul
21290 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 d use SQLITE3_TE
212a0 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 XT, not.** SQLIT
212b0 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 E_TEXT..*/.#defi
212c0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 ne SQLITE_INTEGE
212d0 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c R 1.#define SQL
212e0 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 ITE_FLOAT 2.#
212f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c define SQLITE_BL
21300 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 OB 4.#define
21310 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 SQLITE_NULL
21320 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5.#ifdef SQLITE
21330 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 _TEXT.# undef SQ
21340 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a LITE_TEXT.#else.
21350 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f # define SQLITE_
21360 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 TEXT 3.#endi
21370 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 f.#define SQLITE
21380 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 3_TEXT 3../*
21390 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 .** CAPI3REF: Re
213a0 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d sult Values From
213b0 20 41 20 51 75 65 72 79 20 7b 48 31 33 38 30 30 A Query {H13800
213c0 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 } <S10700>.** KE
213d0 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 YWORDS: {column
213e0 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 access functions
213f0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f }.**.** These ro
21400 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 utines form the
21410 22 72 65 73 75 6c 74 20 73 65 74 20 71 75 65 72 "result set quer
21420 79 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a y" interface..**
21430 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
21440 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d es return inform
21450 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 ation about a si
21460 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 ngle column of t
21470 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 he current.** re
21480 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 sult row of a qu
21490 65 72 79 2e 20 20 49 6e 20 65 76 65 72 79 20 63 ery. In every c
214a0 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 ase the first ar
214b0 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e gument is a poin
214c0 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 ter.** to the [p
214d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
214e0 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 t] that is being
214f0 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 evaluated (the
21500 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a [sqlite3_stmt*].
21510 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75 ** that was retu
21520 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 rned from [sqlit
21530 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
21540 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 or one of its v
21550 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 ariants).** and
21560 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d the second argum
21570 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 ent is the index
21580 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 of the column f
21590 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 or which informa
215a0 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 tion.** should b
215b0 65 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 e returned. The
215c0 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e leftmost column
215d0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 of the result s
215e0 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 et has the index
215f0 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 0..**.** If the
21600 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 SQL statement d
21610 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c oes not currentl
21620 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c y point to a val
21630 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 id row, or if th
21640 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 e.** column inde
21650 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 x is out of rang
21660 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 e, the result is
21670 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 undefined..** T
21680 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 hese routines ma
21690 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 y only be called
216a0 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 when the most r
216b0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a ecent call to.**
216c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
216d0 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b ] has returned [
216e0 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 SQLITE_ROW] and
216f0 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 neither.** [sqli
21700 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 te3_reset()] nor
21710 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
21720 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 ze()] have been
21730 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e called subsequen
21740 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f tly..** If any o
21750 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
21760 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 are called afte
21770 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 r [sqlite3_reset
21780 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 ()] or.** [sqlit
21790 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f e3_finalize()] o
217a0 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 r after [sqlite3
217b0 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 _step()] has ret
217c0 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 urned.** somethi
217d0 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 ng other than [S
217e0 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 QLITE_ROW], the
217f0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 results are unde
21800 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 fined..** If [sq
21810 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 lite3_step()] or
21820 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
21830 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 )] or [sqlite3_f
21840 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 inalize()].** ar
21850 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 e called from a
21860 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 different thread
21870 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 while any of th
21880 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 ese routines.**
21890 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 are pending, the
218a0 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 n the results ar
218b0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a e undefined..**.
218c0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 ** The sqlite3_c
218d0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 olumn_type() rou
218e0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 tine returns the
218f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 .** [SQLITE_INTE
21900 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 GER | datatype c
21910 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 ode] for the ini
21920 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a tial data type.*
21930 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 * of the result
21940 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72 65 74 column. The ret
21950 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f urned value is o
21960 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e ne of [SQLITE_IN
21970 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 TEGER],.** [SQLI
21980 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 TE_FLOAT], [SQLI
21990 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 TE_TEXT], [SQLIT
219a0 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c E_BLOB], or [SQL
219b0 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 ITE_NULL]. The
219c0 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 value.** returne
219d0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c d by sqlite3_col
219e0 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e umn_type() is on
219f0 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 ly meaningful if
21a00 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 no type.** conv
21a10 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 ersions have occ
21a20 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62 urred as describ
21a30 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 ed below. After
21a40 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 a type conversi
21a50 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 on,.** the value
21a60 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
21a70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 ite3_column_type
21a80 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e () is undefined.
21a90 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 Future.** vers
21aa0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d ions of SQLite m
21ab0 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 ay change the be
21ac0 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 havior of sqlite
21ad0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 3_column_type().
21ae0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 ** following a t
21af0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a ype conversion..
21b00 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 **.** If the res
21b10 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 ult is a BLOB or
21b20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 UTF-8 string th
21b30 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 en the sqlite3_c
21b40 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a olumn_bytes().**
21b50 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
21b60 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
21b70 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f ytes in that BLO
21b80 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 B or string..**
21b90 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 If the result is
21ba0 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 a UTF-16 string
21bb0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 , then sqlite3_c
21bc0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f olumn_bytes() co
21bd0 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 nverts.** the st
21be0 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e ring to UTF-8 an
21bf0 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 d then returns t
21c00 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
21c10 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 es..** If the re
21c20 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 sult is a numeri
21c30 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c c value then sql
21c40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
21c50 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c s() uses.** [sql
21c60 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d ite3_snprintf()]
21c70 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 to convert that
21c80 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d value to a UTF-
21c90 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 8 string and ret
21ca0 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 urns.** the numb
21cb0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
21cc0 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 hat string..** T
21cd0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
21ce0 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 d does not inclu
21cf0 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d de the zero term
21d00 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e inator at the en
21d10 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 d.** of the stri
21d20 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72 69 74 79 ng. For clarity
21d30 3a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 : the value retu
21d40 72 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62 rned is the numb
21d50 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 er of.** bytes i
21d60 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f n the string, no
21d70 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 t the number of
21d80 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a characters..**.*
21d90 2a 20 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e * Strings return
21da0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f ed by sqlite3_co
21db0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 lumn_text() and
21dc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
21dd0 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e ext16(),.** even
21de0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 empty strings,
21df0 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 are always zero
21e00 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 terminated. The
21e10 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 return.** value
21e20 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f from sqlite3_co
21e30 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 lumn_blob() for
21e40 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c a zero-length BL
21e50 4f 42 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 OB is an arbitra
21e60 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70 ry.** pointer, p
21e70 6f 73 73 69 62 6c 79 20 65 76 65 6e 20 61 20 4e ossibly even a N
21e80 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a ULL pointer..**.
21e90 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 ** The sqlite3_c
21ea0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 olumn_bytes16()
21eb0 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c routine is simil
21ec0 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ar to sqlite3_co
21ed0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 lumn_bytes().**
21ee0 62 75 74 20 6c 65 61 76 65 73 20 74 68 65 20 72 but leaves the r
21ef0 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31 36 20 esult in UTF-16
21f00 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f in native byte o
21f10 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 rder instead of
21f20 55 54 46 2d 38 2e 0a 2a 2a 20 54 68 65 20 7a 65 UTF-8..** The ze
21f30 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 73 ro terminator is
21f40 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 6e not included in
21f50 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a this count..**.
21f60 2a 2a 20 54 68 65 20 6f 62 6a 65 63 74 20 72 65 ** The object re
21f70 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
21f80 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 e3_column_value(
21f90 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 )] is an.** [unp
21fa0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
21fb0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 _value] object.
21fc0 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 An unprotected
21fd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
21fe0 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 ject.** may only
21ff0 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 be used with [s
22000 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 qlite3_bind_valu
22010 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 e()] and [sqlite
22020 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 3_result_value()
22030 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e ]..** If the [un
22040 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
22050 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
22060 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b returned by.** [
22070 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 sqlite3_column_v
22080 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 alue()] is used
22090 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 in any other way
220a0 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c , including call
220b0 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 s.** to routines
220c0 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 like [sqlite3_v
220d0 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 alue_int()], [sq
220e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
220f0 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 ()],.** or [sqli
22100 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 te3_value_bytes(
22110 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 )], then the beh
22120 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e avior is undefin
22130 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ed..**.** These
22140 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 routines attempt
22150 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 to convert the
22160 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 value where appr
22170 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a opriate. For.**
22180 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 example, if the
22190 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 internal repres
221a0 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 entation is FLOA
221b0 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 T and a text res
221c0 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 ult.** is reques
221d0 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e ted, [sqlite3_sn
221e0 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 printf()] is use
221f0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 d internally to
22200 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 perform the.** c
22210 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 onversion automa
22220 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f tically. The fo
22230 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 llowing table de
22240 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 tails the conver
22250 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 sions.** that ar
22260 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a e applied:.**.**
22270 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a <blockquote>.**
22280 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 <table border="
22290 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 1">.** <tr><th>
222a0 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 Internal<br>Type
222b0 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c <th> Requested<
222c0 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f br>Type <th> Co
222d0 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c nversion.**.** <
222e0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 tr><td> NULL
222f0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 <td> INTEGER
22300 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 <td> Result is 0
22310 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 .** <tr><td> NU
22320 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 LL <td> FLOA
22330 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 T <td> Result
22340 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c is 0.0.** <tr><
22350 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 td> NULL <td
22360 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e > TEXT <td>
22370 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 Result is NULL
22380 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c pointer.** <tr><
22390 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 td> NULL <td
223a0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e > BLOB <td>
223b0 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 Result is NULL
223c0 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c pointer.** <tr><
223d0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 td> INTEGER <td
223e0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e > FLOAT <td>
223f0 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e Convert from in
22400 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a teger to float.*
22410 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 * <tr><td> INTEG
22420 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 ER <td> TEXT
22430 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 <td> ASCII re
22440 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 ndering of the i
22450 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 nteger.** <tr><t
22460 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e d> INTEGER <td>
22470 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 BLOB <td>
22480 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d Same as INTEGER-
22490 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 >TEXT.** <tr><td
224a0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 > FLOAT <td>
224b0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 INTEGER <td> C
224c0 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 onvert from floa
224d0 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 t to integer.**
224e0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 <tr><td> FLOAT
224f0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 <td> TEXT
22500 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 <td> ASCII rend
22510 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f ering of the flo
22520 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 at.** <tr><td>
22530 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 FLOAT <td> B
22540 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 LOB <td> Same
22550 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a as FLOAT->TEXT.
22560 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 ** <tr><td> TEX
22570 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 T <td> INTEGE
22580 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f R <td> Use ato
22590 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 i().** <tr><td>
225a0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 TEXT <td> F
225b0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 LOAT <td> Use
225c0 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c atof().** <tr><
225d0 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 td> TEXT <td
225e0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e > BLOB <td>
225f0 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 No change.** <t
22600 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 r><td> BLOB
22610 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c <td> INTEGER <
22620 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 td> Convert to T
22630 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f EXT then use ato
22640 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 i().** <tr><td>
22650 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 BLOB <td> F
22660 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e LOAT <td> Con
22670 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 vert to TEXT the
22680 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 n use atof().**
22690 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 <tr><td> BLOB
226a0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 <td> TEXT
226b0 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f <td> Add a zero
226c0 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e terminator if n
226d0 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 eeded.** </table
226e0 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 >.** </blockquot
226f0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 e>.**.** The tab
22700 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 le above makes r
22710 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e eference to stan
22720 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 dard C library f
22730 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a unctions atoi().
22740 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 ** and atof().
22750 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 SQLite does not
22760 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 really use these
22770 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 functions. It
22780 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 has its.** own e
22790 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e quivalent intern
227a0 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 al routines. Th
227b0 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f e atoi() and ato
227c0 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a f() names are.**
227d0 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 used in the tab
227e0 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 le for brevity a
227f0 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20 nd because they
22800 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 are familiar to
22810 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 most.** C progra
22820 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 mmers..**.** Not
22830 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 e that when type
22840 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 conversions occ
22850 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 ur, pointers ret
22860 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a urned by prior.*
22870 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 * calls to sqlit
22880 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 e3_column_blob()
22890 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e , sqlite3_column
228a0 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a _text(), and/or.
228b0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d ** sqlite3_colum
228c0 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 n_text16() may b
228d0 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a e invalidated..*
228e0 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f * Type conversio
228f0 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 ns and pointer i
22900 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 nvalidations mig
22910 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 ht occur.** in t
22920 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 he following cas
22930 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a es:.**.** <ul>.*
22940 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 * <li> The initi
22950 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 al content is a
22960 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 BLOB and sqlite3
22970 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f _column_text() o
22980 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 r.** sqlite
22990 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
229a0 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 ) is called. A
229b0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 zero-terminator
229c0 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 might.** ne
229d0 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 ed to be added t
229e0 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c o the string.</l
229f0 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 i>.** <li> The i
22a00 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 nitial content i
22a10 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 s UTF-8 text and
22a20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
22a30 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 bytes16() or.**
22a40 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c sqlite3_col
22a50 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 umn_text16() is
22a60 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e called. The con
22a70 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e tent must be con
22a80 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 verted.** t
22a90 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a o UTF-16.</li>.*
22aa0 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 * <li> The initi
22ab0 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 al content is UT
22ac0 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 F-16 text and sq
22ad0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
22ae0 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 es() or.**
22af0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
22b00 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e ext() is called.
22b10 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 The content mu
22b20 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a st be converted.
22b30 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 ** to UTF-8
22b40 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a .</li>.** </ul>.
22b50 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e **.** Conversion
22b60 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 s between UTF-16
22b70 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 be and UTF-16le
22b80 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 are always done
22b90 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a in place and do.
22ba0 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 ** not invalidat
22bb0 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 e a prior pointe
22bc0 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 r, though of cou
22bd0 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 rse the content
22be0 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a of the buffer.**
22bf0 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 that the prior
22c00 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 pointer points t
22c10 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e o will have been
22c20 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 modified. Othe
22c30 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f r kinds.** of co
22c40 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e nversion are don
22c50 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 e in place when
22c60 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 it is possible,
22c70 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 but sometimes th
22c80 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f ey.** are not po
22c90 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 ssible and in th
22ca0 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 ose cases prior
22cb0 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 pointers are inv
22cc0 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 alidated..**.**
22cd0 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 The safest and e
22ce0 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 asiest to rememb
22cf0 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 er policy is to
22d00 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 invoke these rou
22d10 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 tines.** in one
22d20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 of the following
22d30 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c ways:.**.** <ul
22d40 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 >.** <li>sqlite
22d50 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 3_column_text()
22d60 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 followed by sqli
22d70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
22d80 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e ()</li>.** <li>
22d90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
22da0 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 lob() followed b
22db0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e y sqlite3_column
22dc0 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a _bytes()</li>.**
22dd0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f <li>sqlite3_co
22de0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f lumn_text16() fo
22df0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 llowed by sqlite
22e00 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
22e10 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e ()</li>.** </ul>
22e20 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 .**.** In other
22e30 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c words, you shoul
22e40 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 d call sqlite3_c
22e50 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a olumn_text(),.**
22e60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
22e70 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 blob(), or sqlit
22e80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
22e90 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 () first to forc
22ea0 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 e the result.**
22eb0 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 into the desired
22ec0 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e format, then in
22ed0 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c voke sqlite3_col
22ee0 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a umn_bytes() or.*
22ef0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e * sqlite3_column
22f00 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 _bytes16() to fi
22f10 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 nd the size of t
22f20 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e he result. Do n
22f30 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 ot mix calls.**
22f40 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d to sqlite3_colum
22f50 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 n_text() or sqli
22f60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
22f70 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a ) with calls to.
22f80 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d ** sqlite3_colum
22f90 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 n_bytes16(), and
22fa0 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c do not mix call
22fb0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c s to sqlite3_col
22fc0 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 umn_text16().**
22fd0 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 with calls to sq
22fe0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
22ff0 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 es()..**.** The
23000 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 pointers returne
23010 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 d are valid unti
23020 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 l a type convers
23030 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a ion occurs as.**
23040 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 described above
23050 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 , or until [sqli
23060 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b te3_step()] or [
23070 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
23080 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
23090 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 finalize()] is c
230a0 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65 6d 6f alled. The memo
230b0 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f ry space used to
230c0 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a hold strings.**
230d0 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 and BLOBs is fr
230e0 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c eed automaticall
230f0 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 y. Do <b>not</b
23100 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 > pass the point
23110 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 ers returned.**
23120 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
23130 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 blob()], [sqlite
23140 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 3_column_text()]
23150 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b , etc. into.** [
23160 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e sqlite3_free()].
23170 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d 65 6d 6f .**.** If a memo
23180 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 ry allocation er
23190 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e ror occurs durin
231a0 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e g the evaluation
231b0 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 of any.** of th
231c0 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 ese routines, a
231d0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 default value is
231e0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 returned. The
231f0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a default value.**
23200 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 is either the i
23210 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c nteger 0, the fl
23220 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d oating point num
23230 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 ber 0.0, or a NU
23240 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 LL.** pointer.
23250 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 Subsequent calls
23260 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 to [sqlite3_err
23270 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 code()] will ret
23280 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e urn.** [SQLITE_N
23290 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 OMEM]..**.** Req
232a0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
232b0 31 33 38 30 33 5d 20 5b 48 31 33 38 30 36 5d 20 13803] [H13806]
232c0 5b 48 31 33 38 30 39 5d 20 5b 48 31 33 38 31 32 [H13809] [H13812
232d0 5d 20 5b 48 31 33 38 31 35 5d 20 5b 48 31 33 38 ] [H13815] [H138
232e0 31 38 5d 20 5b 48 31 33 38 32 31 5d 20 5b 48 31 18] [H13821] [H1
232f0 33 38 32 34 5d 0a 2a 2a 20 5b 48 31 33 38 32 37 3824].** [H13827
23300 5d 20 5b 48 31 33 38 33 30 5d 0a 2a 2f 0a 53 51 ] [H13830].*/.SQ
23310 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 LITE_API const v
23320 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c oid *sqlite3_col
23330 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 umn_blob(sqlite3
23340 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
23350 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
23360 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e t sqlite3_column
23370 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 _bytes(sqlite3_s
23380 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
23390 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
233a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
233b0 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 ytes16(sqlite3_s
233c0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
233d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 .SQLITE_API doub
233e0 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d le sqlite3_colum
233f0 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 n_double(sqlite3
23400 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
23410 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
23420 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e t sqlite3_column
23430 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d _int(sqlite3_stm
23440 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 t*, int iCol);.S
23450 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 QLITE_API sqlite
23460 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 3_int64 sqlite3_
23470 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c column_int64(sql
23480 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
23490 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 iCol);.SQLITE_AP
234a0 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 I const unsigned
234b0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 char *sqlite3_c
234c0 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 olumn_text(sqlit
234d0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
234e0 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 ol);.SQLITE_API
234f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
23500 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
23510 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
23520 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 int iCol);.SQLI
23530 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
23540 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 e3_column_type(s
23550 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
23560 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f t iCol);.SQLITE_
23570 41 50 49 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 API sqlite3_valu
23580 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d e *sqlite3_colum
23590 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f n_value(sqlite3_
235a0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
235b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
235c0 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 F: Destroy A Pre
235d0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 pared Statement
235e0 4f 62 6a 65 63 74 20 7b 48 31 33 33 30 30 7d 20 Object {H13300}
235f0 3c 53 37 30 33 30 30 3e 3c 53 33 30 31 30 30 3e <S70300><S30100>
23600 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
23610 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 e3_finalize() fu
23620 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 nction is called
23630 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 to delete a [pr
23640 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
23650 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73 74 61 ]..** If the sta
23660 74 65 6d 65 6e 74 20 77 61 73 20 65 78 65 63 75 tement was execu
23670 74 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 ted successfully
23680 20 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65 64 or not executed
23690 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a 2a at all, then.**
236a0 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 SQLITE_OK is re
236b0 74 75 72 6e 65 64 2e 20 49 66 20 65 78 65 63 75 turned. If execu
236c0 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 tion of the stat
236d0 65 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65 ement failed the
236e0 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 n an.** [error c
236f0 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 ode] or [extende
23700 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 d error code] is
23710 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
23720 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 This routine ca
23730 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 n be called at a
23740 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 ny point during
23750 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 the execution of
23760 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the.** [prepare
23770 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 d statement]. I
23780 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61 f the virtual ma
23790 63 68 69 6e 65 20 68 61 73 20 6e 6f 74 0a 2a 2a chine has not.**
237a0 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 completed execu
237b0 74 69 6f 6e 20 77 68 65 6e 20 74 68 69 73 20 72 tion when this r
237c0 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 outine is called
237d0 2c 20 74 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a , that is like.*
237e0 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 * encountering a
237f0 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e 20 5b 73 n error or an [s
23800 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
23810 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 2e 0a 2a | interrupt]..*
23820 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 * Incomplete upd
23830 61 74 65 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c ates may be roll
23840 65 64 20 62 61 63 6b 20 61 6e 64 20 74 72 61 6e ed back and tran
23850 73 61 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c 65 sactions cancele
23860 64 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20 d,.** depending
23870 6f 6e 20 74 68 65 20 63 69 72 63 75 6d 73 74 61 on the circumsta
23880 6e 63 65 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a nces, and the.**
23890 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 72 65 [error code] re
238a0 74 75 72 6e 65 64 20 77 69 6c 6c 20 62 65 20 5b turned will be [
238b0 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a SQLITE_ABORT]..*
238c0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
238d0 73 3a 0a 2a 2a 20 5b 48 31 31 33 30 32 5d 20 5b s:.** [H11302] [
238e0 48 31 31 33 30 34 5d 0a 2a 2f 0a 53 51 4c 49 54 H11304].*/.SQLIT
238f0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
23900 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 3_finalize(sqlit
23910 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b e3_stmt *pStmt);
23920 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
23930 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 : Reset A Prepar
23940 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a ed Statement Obj
23950 65 63 74 20 7b 48 31 33 33 33 30 7d 20 3c 53 37 ect {H13330} <S7
23960 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 0300>.**.** The
23970 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 sqlite3_reset()
23980 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c function is call
23990 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 ed to reset a [p
239a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
239b0 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 t].** object bac
239c0 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c k to its initial
239d0 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f state, ready to
239e0 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e be re-executed.
239f0 0a 2a 2a 20 41 6e 79 20 53 51 4c 20 73 74 61 74 .** Any SQL stat
23a00 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 ement variables
23a10 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 that had values
23a20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 bound to them us
23a30 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 ing.** the [sqli
23a40 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 te3_bind_blob |
23a50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 sqlite3_bind_*()
23a60 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 API] retain the
23a70 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 ir values..** Us
23a80 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 e [sqlite3_clear
23a90 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 _bindings()] to
23aa0 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e reset the bindin
23ab0 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 gs..**.** {H1133
23ac0 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 2} The [sqlite3_
23ad0 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 reset(S)] interf
23ae0 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b ace resets the [
23af0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
23b00 6e 74 5d 20 53 0a 2a 2a 20 20 20 20 20 20 20 20 nt] S.**
23b10 20 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 back to the be
23b20 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 ginning of its p
23b30 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 rogram..**.** {H
23b40 31 31 33 33 34 7d 20 49 66 20 74 68 65 20 6d 6f 11334} If the mo
23b50 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 st recent call t
23b60 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 o [sqlite3_step(
23b70 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 S)] for the.**
23b80 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 [prepare
23b90 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 d statement] S r
23ba0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f eturned [SQLITE_
23bb0 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f ROW] or [SQLITE_
23bc0 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 DONE],.**
23bd0 20 20 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 or if [sqlite
23be0 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 3_step(S)] has n
23bf0 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e ever before been
23c00 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a called on S,.**
23c10 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b then [
23c20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 sqlite3_reset(S)
23c30 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 ] returns [SQLIT
23c40 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 E_OK]..**.** {H1
23c50 31 33 33 36 7d 20 49 66 20 74 68 65 20 6d 6f 73 1336} If the mos
23c60 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f t recent call to
23c70 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 [sqlite3_step(S
23c80 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 )] for the.**
23c90 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 [prepared
23ca0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e statement] S in
23cb0 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 dicated an error
23cc0 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 , then.**
23cd0 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 [sqlite3_rese
23ce0 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e t(S)] returns an
23cf0 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 appropriate [er
23d00 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a ror code]..**.**
23d10 20 7b 48 31 31 33 33 38 7d 20 54 68 65 20 5b 73 {H11338} The [s
23d20 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d qlite3_reset(S)]
23d30 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 interface does
23d40 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 not change the v
23d50 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 alues.**
23d60 20 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 of any [sqlite
23d70 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 3_bind_blob|bind
23d80 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 ings] on the [pr
23d90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
23da0 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ] S..*/.SQLITE_A
23db0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 PI int sqlite3_r
23dc0 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d eset(sqlite3_stm
23dd0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
23de0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 * CAPI3REF: Crea
23df0 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 te Or Redefine S
23e00 51 4c 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 QL Functions {H1
23e10 36 31 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 6100} <S20200>.*
23e20 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e * KEYWORDS: {fun
23e30 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 ction creation r
23e40 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 outines}.** KEYW
23e50 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 ORDS: {applicati
23e60 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 on-defined SQL f
23e70 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 unction}.** KEYW
23e80 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 ORDS: {applicati
23e90 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 on-defined SQL f
23ea0 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 unctions}.**.**
23eb0 54 68 65 73 65 20 74 77 6f 20 66 75 6e 63 74 69 These two functi
23ec0 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c ons (collectivel
23ed0 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 y known as "func
23ee0 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f tion creation ro
23ef0 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 utines").** are
23f00 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 used to add SQL
23f10 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 functions or agg
23f20 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 regates or to re
23f30 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 define the behav
23f40 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 ior.** of existi
23f50 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 ng SQL functions
23f60 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 or aggregates.
23f70 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 The only differ
23f80 65 6e 63 65 20 62 65 74 77 65 65 6e 20 74 68 65 ence between the
23f90 0a 2a 2a 20 74 77 6f 20 69 73 20 74 68 61 74 20 .** two is that
23fa0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
23fb0 65 74 65 72 2c 20 74 68 65 20 6e 61 6d 65 20 6f eter, the name o
23fc0 66 20 74 68 65 20 28 73 63 61 6c 61 72 29 20 66 f the (scalar) f
23fd0 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 unction or.** ag
23fe0 67 72 65 67 61 74 65 2c 20 69 73 20 65 6e 63 6f gregate, is enco
23ff0 64 65 64 20 69 6e 20 55 54 46 2d 38 20 66 6f 72 ded in UTF-8 for
24000 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
24010 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 function() and U
24020 54 46 2d 31 36 0a 2a 2a 20 66 6f 72 20 73 71 6c TF-16.** for sql
24030 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
24040 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 tion16()..**.**
24050 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 The first parame
24060 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 ter is the [data
24070 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
24080 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 to which the SQ
24090 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 L.** function is
240a0 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 49 to be added. I
240b0 66 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 f a single progr
240c0 61 6d 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 am uses more tha
240d0 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a n one database.*
240e0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 6e 74 * connection int
240f0 65 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51 ernally, then SQ
24100 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 L functions must
24110 20 62 65 20 61 64 64 65 64 20 69 6e 64 69 76 69 be added indivi
24120 64 75 61 6c 6c 79 20 74 6f 0a 2a 2a 20 65 61 63 dually to.** eac
24130 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 h database conne
24140 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ction..**.** The
24150 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
24160 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 r is the name of
24170 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
24180 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 n to be created
24190 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e or.** redefined.
241a0 20 20 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 The length of
241b0 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 the name is limi
241c0 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 ted to 255 bytes
241d0 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 0a 2a , exclusive of.*
241e0 2a 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 * the zero-termi
241f0 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 nator. Note tha
24200 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 t the name lengt
24210 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79 h limit is in by
24220 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 tes, not.** char
24230 61 63 74 65 72 73 2e 20 20 41 6e 79 20 61 74 74 acters. Any att
24240 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 empt to create a
24250 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 function with a
24260 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 longer name.**
24270 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b will result in [
24280 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 62 65 SQLITE_ERROR] be
24290 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a ing returned..**
242a0 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 70 61 .** The third pa
242b0 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a rameter (nArg).*
242c0 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 * is the number
242d0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 of arguments tha
242e0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 t the SQL functi
242f0 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 on or.** aggrega
24300 74 65 20 74 61 6b 65 73 2e 20 49 66 20 74 68 69 te takes. If thi
24310 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d s parameter is -
24320 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 1, then the SQL
24330 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 function or.** a
24340 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b ggregate may tak
24350 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 e any number of
24360 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 arguments betwee
24370 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 n 0 and the limi
24380 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c t.** set by [sql
24390 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c ite3_limit]([SQL
243a0 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 ITE_LIMIT_FUNCTI
243b0 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 ON_ARG]). If th
243c0 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d e third.** param
243d0 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 eter is less tha
243e0 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 n -1 or greater
243f0 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 than 127 then th
24400 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a e behavior is.**
24410 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
24420 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 * The fourth par
24430 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 ameter, eTextRep
24440 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 , specifies what
24450 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 .** [SQLITE_UTF8
24460 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 | text encoding
24470 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 ] this SQL funct
24480 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a ion prefers for.
24490 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 ** its parameter
244a0 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e 63 s. Any SQL func
244b0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 tion implementat
244c0 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61 62 ion should be ab
244d0 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f le to work.** wo
244e0 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 rk with UTF-8, U
244f0 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d TF-16le, or UTF-
24500 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 16be. But some
24510 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
24520 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 may be.** more e
24530 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e fficient with on
24540 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 e encoding than
24550 61 6e 6f 74 68 65 72 2e 20 20 41 6e 20 61 70 70 another. An app
24560 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 lication may.**
24570 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 invoke sqlite3_c
24580 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
24590 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 or sqlite3_crea
245a0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 te_function16()
245b0 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 multiple.** time
245c0 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 s with the same
245d0 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 function but wit
245e0 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 h different valu
245f0 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a es of eTextRep..
24600 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 ** When multiple
24610 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
24620 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e of the same fun
24630 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 ction are availa
24640 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 ble, SQLite.** w
24650 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 ill pick the one
24660 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 that involves t
24670 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 he least amount
24680 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 of data conversi
24690 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 on..** If there
246a0 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 is only a single
246b0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
246c0 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 which does not c
246d0 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a are what text.**
246e0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 encoding is use
246f0 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 d, then the four
24700 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 th argument shou
24710 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e ld be [SQLITE_AN
24720 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 Y]..**.** The fi
24730 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 fth parameter is
24740 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f an arbitrary po
24750 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c inter. The impl
24760 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 ementation of th
24770 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 e.** function ca
24780 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f n gain access to
24790 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 this pointer us
247a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 ing [sqlite3_use
247b0 72 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a r_data()]..**.**
247c0 20 54 68 65 20 73 65 76 65 6e 74 68 2c 20 65 69 The seventh, ei
247d0 67 68 74 68 20 61 6e 64 20 6e 69 6e 74 68 20 70 ghth and ninth p
247e0 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 arameters, xFunc
247f0 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e , xStep and xFin
24800 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 al, are.** point
24810 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 ers to C-languag
24820 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 e functions that
24830 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 implement the S
24840 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a QL function or.*
24850 2a 20 61 67 67 72 65 67 61 74 65 2e 20 41 20 73 * aggregate. A s
24860 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 calar SQL functi
24870 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 on requires an i
24880 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
24890 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 the xFunc.** ca
248a0 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c llback only, NUL
248b0 4c 20 70 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c L pointers shoul
248c0 64 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 d be passed as t
248d0 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 he xStep and xFi
248e0 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 nal.** parameter
248f0 73 2e 20 41 6e 20 61 67 67 72 65 67 61 74 65 20 s. An aggregate
24900 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 SQL function req
24910 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 uires an impleme
24920 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 ntation of xStep
24930 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 .** and xFinal a
24940 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 nd NULL should b
24950 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 e passed for xFu
24960 6e 63 2e 20 54 6f 20 64 65 6c 65 74 65 20 61 6e nc. To delete an
24970 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c existing.** SQL
24980 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 function or agg
24990 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c regate, pass NUL
249a0 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 L for all three
249b0 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 function callbac
249c0 6b 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 ks..**.** It is
249d0 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 permitted to reg
249e0 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 ister multiple i
249f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f mplementations o
24a00 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 f the same.** fu
24a10 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 nctions with the
24a20 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 same name but w
24a30 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65 ith either diffe
24a40 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a ring numbers of.
24a50 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 ** arguments or
24a60 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 differing prefer
24a70 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e red text encodin
24a80 67 73 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c gs. SQLite will
24a90 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c use.** the impl
24aa0 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 ementation that
24ab0 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 most closely mat
24ac0 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 ches the way in
24ad0 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c which the.** SQL
24ae0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 function is use
24af0 64 2e 20 20 41 20 66 75 6e 63 74 69 6f 6e 20 69 d. A function i
24b00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 mplementation wi
24b10 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 th a non-negativ
24b20 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 e.** nArg parame
24b30 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20 ter is a better
24b40 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e match than a fun
24b50 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 ction implementa
24b60 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e tion with.** a n
24b70 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 41 egative nArg. A
24b80 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 function where
24b90 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65 the preferred te
24ba0 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d xt encoding.** m
24bb0 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62 atches the datab
24bc0 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 ase encoding is
24bd0 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 a better.** matc
24be0 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f h than a functio
24bf0 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f n where the enco
24c00 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e ding is differen
24c10 74 2e 20 20 0a 2a 2a 20 41 20 66 75 6e 63 74 69 t. .** A functi
24c20 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 on where the enc
24c30 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 oding difference
24c40 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 is between UTF1
24c50 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 6le and UTF16be.
24c60 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d ** is a closer m
24c70 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 atch than a func
24c80 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 tion where the e
24c90 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e ncoding differen
24ca0 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e ce is.** between
24cb0 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e UTF8 and UTF16.
24cc0 0a 2a 2a 0a 2a 2a 20 42 75 69 6c 74 2d 69 6e 20 .**.** Built-in
24cd0 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 functions may be
24ce0 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e overloaded by n
24cf0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 ew application-d
24d00 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 efined functions
24d10 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 ..** The first a
24d20 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
24d30 65 64 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 ed function with
24d40 20 61 20 67 69 76 65 6e 20 6e 61 6d 65 20 6f 76 a given name ov
24d50 65 72 72 69 64 65 73 20 61 6c 6c 0a 2a 2a 20 62 errides all.** b
24d60 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e uilt-in function
24d70 73 20 69 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 s in the same [d
24d80 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
24d90 6f 6e 5d 20 77 69 74 68 20 74 68 65 20 73 61 6d on] with the sam
24da0 65 20 6e 61 6d 65 2e 0a 2a 2a 20 53 75 62 73 65 e name..** Subse
24db0 71 75 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f quent applicatio
24dc0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
24dd0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 ons of the same
24de0 6e 61 6d 65 20 6f 6e 6c 79 20 6f 76 65 72 72 69 name only overri
24df0 64 65 20 0a 2a 2a 20 70 72 69 6f 72 20 61 70 70 de .** prior app
24e00 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
24e10 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 functions that
24e20 61 72 65 20 61 6e 20 65 78 61 63 74 20 6d 61 74 are an exact mat
24e30 63 68 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6e 75 ch for the.** nu
24e40 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 mber of paramete
24e50 72 73 20 61 6e 64 20 70 72 65 66 65 72 72 65 64 rs and preferred
24e60 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a encoding..**.**
24e70 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d An application-
24e80 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
24e90 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f is permitted to
24ea0 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 call other.** S
24eb0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 QLite interfaces
24ec0 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 . However, such
24ed0 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a calls must not.
24ee0 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 ** close the dat
24ef0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
24f00 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 nor finalize or
24f10 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 reset the prepa
24f20 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 red.** statement
24f30 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 in which the fu
24f40 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e nction is runnin
24f50 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 g..**.** Require
24f60 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 31 30 ments:.** [H1610
24f70 33 5d 20 5b 48 31 36 31 30 36 5d 20 5b 48 31 36 3] [H16106] [H16
24f80 31 30 39 5d 20 5b 48 31 36 31 31 32 5d 20 5b 48 109] [H16112] [H
24f90 31 36 31 31 38 5d 20 5b 48 31 36 31 32 31 5d 20 16118] [H16121]
24fa0 5b 48 31 36 31 32 37 5d 0a 2a 2a 20 5b 48 31 36 [H16127].** [H16
24fb0 31 33 30 5d 20 5b 48 31 36 31 33 33 5d 20 5b 48 130] [H16133] [H
24fc0 31 36 31 33 36 5d 20 5b 48 31 36 31 33 39 5d 20 16136] [H16139]
24fd0 5b 48 31 36 31 34 32 5d 0a 2a 2f 0a 53 51 4c 49 [H16142].*/.SQLI
24fe0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
24ff0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
25000 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 on(. sqlite3 *d
25010 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 b,. const char
25020 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a *zFunctionName,.
25030 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e int nArg,. in
25040 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f t eTextRep,. vo
25050 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 id *pApp,. void
25060 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 (*xFunc)(sqlite
25070 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 3_context*,int,s
25080 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c qlite3_value**),
25090 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 . void (*xStep)
250a0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
250b0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
250c0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
250d0 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 *xFinal)(sqlite3
250e0 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 _context*).);.SQ
250f0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
25100 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
25110 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 tion16(. sqlite
25120 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 3 *db,. const v
25130 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 oid *zFunctionNa
25140 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a me,. int nArg,.
25150 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a int eTextRep,.
25160 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 void *pApp,.
25170 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 void (*xFunc)(sq
25180 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 lite3_context*,i
25190 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt,sqlite3_value
251a0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 **),. void (*xS
251b0 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e tep)(sqlite3_con
251c0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 text*,int,sqlite
251d0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 3_value**),. vo
251e0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c id (*xFinal)(sql
251f0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 ite3_context*).)
25200 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
25210 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 F: Text Encoding
25220 73 20 7b 48 31 30 32 36 37 7d 20 3c 53 35 30 32 s {H10267} <S502
25230 30 30 3e 20 3c 48 31 36 31 30 30 3e 0a 2a 2a 0a 00> <H16100>.**.
25240 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e ** These constan
25250 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 t define integer
25260 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 codes that repr
25270 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 esent the variou
25280 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 s.** text encodi
25290 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 ngs supported by
252a0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 SQLite..*/.#def
252b0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 ine SQLITE_UTF8
252c0 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 1.#def
252d0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 ine SQLITE_UTF16
252e0 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 LE 2.#def
252f0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 ine SQLITE_UTF16
25300 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 BE 3.#def
25310 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 ine SQLITE_UTF16
25320 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 4 /
25330 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 * Use native byt
25340 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 e order */.#defi
25350 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 ne SQLITE_ANY
25360 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 5 /*
25370 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
25380 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f function only */
25390 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
253a0 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 UTF16_ALIGNED 8
253b0 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 /* sqlite3_c
253c0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 reate_collation
253d0 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 only */../*.** C
253e0 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 API3REF: Depreca
253f0 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a ted Functions.**
25400 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a DEPRECATED.**.*
25410 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e * These function
25420 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 s are [deprecate
25430 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f d]. In order to
25440 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 maintain.** bac
25450 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 kwards compatibi
25460 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 lity with older
25470 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 code, these func
25480 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a tions continue .
25490 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 ** to be support
254a0 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 ed. However, ne
254b0 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 w applications s
254c0 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 hould avoid.** t
254d0 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 he use of these
254e0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 functions. To h
254f0 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 elp encourage pe
25500 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a ople to avoid.**
25510 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e using these fun
25520 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e ctions, we are n
25530 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c ot going to tell
25540 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 you what they d
25550 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 o..*/.#ifndef SQ
25560 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 LITE_OMIT_DEPREC
25570 41 54 45 44 0a 53 51 4c 49 54 45 5f 41 50 49 20 ATED.SQLITE_API
25580 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 SQLITE_DEPRECATE
25590 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 D int sqlite3_ag
255a0 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 gregate_count(sq
255b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b lite3_context*);
255c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 .SQLITE_API SQLI
255d0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e TE_DEPRECATED in
255e0 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 t sqlite3_expire
255f0 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 d(sqlite3_stmt*)
25600 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c ;.SQLITE_API SQL
25610 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 ITE_DEPRECATED i
25620 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 nt sqlite3_trans
25630 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c fer_bindings(sql
25640 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 ite3_stmt*, sqli
25650 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 te3_stmt*);.SQLI
25660 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 TE_API SQLITE_DE
25670 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c PRECATED int sql
25680 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f ite3_global_reco
25690 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 ver(void);.SQLIT
256a0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 E_API SQLITE_DEP
256b0 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c RECATED void sql
256c0 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 ite3_thread_clea
256d0 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 nup(void);.SQLIT
256e0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 E_API SQLITE_DEP
256f0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 RECATED int sqli
25700 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d te3_memory_alarm
25710 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 (void(*)(void*,s
25720 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 qlite3_int64,int
25730 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f ),void*,sqlite3_
25740 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a int64);.#endif..
25750 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
25760 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 Obtaining SQL Fu
25770 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 nction Parameter
25780 20 56 61 6c 75 65 73 20 7b 48 31 35 31 30 30 7d Values {H15100}
25790 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S20200>.**.**
257a0 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 The C-language i
257b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
257c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 SQL functions a
257d0 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73 nd aggregates us
257e0 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f es.** this set o
257f0 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 f interface rout
25800 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 ines to access t
25810 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c he parameter val
25820 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 ues on.** the fu
25830 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 nction or aggreg
25840 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ate..**.** The x
25850 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 Func (for scalar
25860 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 functions) or x
25870 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 Step (for aggreg
25880 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 ates) parameters
25890 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f .** to [sqlite3_
258a0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
258b0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
258c0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 create_function1
258d0 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 6()].** define c
258e0 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d allbacks that im
258f0 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 plement the SQL
25900 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 functions and ag
25910 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 gregates..** The
25920 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 4th parameter t
25930 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b o these callback
25940 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 s is an array of
25950 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 pointers to.**
25960 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 [protected sqlit
25970 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
25980 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 s. There is one
25990 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d [sqlite3_value]
259a0 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 object for.** e
259b0 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f ach parameter to
259c0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
259d0 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e n. These routin
259e0 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a es are used to.*
259f0 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 * extract values
25a00 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 from the [sqlit
25a10 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
25a20 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 s..**.** These r
25a30 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c outines work onl
25a40 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 y with [protecte
25a50 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
25a60 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 objects..** Any
25a70 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 attempt to use
25a80 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f these routines o
25a90 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 n an [unprotecte
25aa0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
25ab0 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c .** object resul
25ac0 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 ts in undefined
25ad0 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 behavior..**.**
25ae0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 These routines w
25af0 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 ork just like th
25b00 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 e corresponding
25b10 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 [column access f
25b20 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 unctions].** exc
25b30 65 70 74 20 74 68 61 74 20 20 74 68 65 73 65 20 ept that these
25b40 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 routines take a
25b50 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 single [protecte
25b60 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
25b70 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 object.** point
25b80 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 er instead of a
25b90 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 [sqlite3_stmt*]
25ba0 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 pointer and an i
25bb0 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 nteger column nu
25bc0 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 mber..**.** The
25bd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
25be0 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 xt16() interface
25bf0 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d extracts a UTF-
25c00 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 16 string.** in
25c10 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d the native byte-
25c20 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 order of the hos
25c30 74 20 6d 61 63 68 69 6e 65 2e 20 20 54 68 65 0a t machine. The.
25c40 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ** sqlite3_value
25c50 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 _text16be() and
25c60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
25c70 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 xt16le() interfa
25c80 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 ces.** extract U
25c90 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 TF-16 strings as
25ca0 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 big-endian and
25cb0 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 little-endian re
25cc0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a spectively..**.*
25cd0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 * The sqlite3_va
25ce0 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 lue_numeric_type
25cf0 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 () interface att
25d00 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a empts to apply.*
25d10 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 * numeric affini
25d20 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e ty to the value.
25d30 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 This means tha
25d40 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a t an attempt is.
25d50 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 ** made to conve
25d60 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 rt the value to
25d70 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c an integer or fl
25d80 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 oating point. I
25d90 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 f.** such a conv
25da0 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 ersion is possib
25db0 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 le without loss
25dc0 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 of information (
25dd0 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 in other.** word
25de0 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 s, if the value
25df0 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 is a string that
25e00 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 looks like a nu
25e10 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 mber).** then th
25e20 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 e conversion is
25e30 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 performed. Othe
25e40 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 rwise no convers
25e50 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 ion occurs..** T
25e60 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 he [SQLITE_INTEG
25e70 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 ER | datatype] a
25e80 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 fter conversion
25e90 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a is returned..**.
25ea0 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 ** Please pay pa
25eb0 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 rticular attenti
25ec0 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 on to the fact t
25ed0 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 hat the pointer
25ee0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d returned.** from
25ef0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
25f00 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 blob()], [sqlite
25f10 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 3_value_text()],
25f20 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
25f30 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 value_text16()]
25f40 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 can be invalidat
25f50 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65 ed by a subseque
25f60 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 nt call to.** [s
25f70 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 qlite3_value_byt
25f80 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f es()], [sqlite3_
25f90 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d value_bytes16()]
25fa0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 , [sqlite3_value
25fb0 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 _text()],.** or
25fc0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 [sqlite3_value_t
25fd0 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 ext16()]..**.**
25fe0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d These routines m
25ff0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 ust be called fr
26000 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 om the same thre
26010 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c ad as.** the SQL
26020 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 function that s
26030 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c upplied the [sql
26040 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 ite3_value*] par
26050 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 52 ameters..**.** R
26060 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
26070 5b 48 31 35 31 30 33 5d 20 5b 48 31 35 31 30 36 [H15103] [H15106
26080 5d 20 5b 48 31 35 31 30 39 5d 20 5b 48 31 35 31 ] [H15109] [H151
26090 31 32 5d 20 5b 48 31 35 31 31 35 5d 20 5b 48 31 12] [H15115] [H1
260a0 35 31 31 38 5d 20 5b 48 31 35 31 32 31 5d 20 5b 5118] [H15121] [
260b0 48 31 35 31 32 34 5d 0a 2a 2a 20 5b 48 31 35 31 H15124].** [H151
260c0 32 37 5d 20 5b 48 31 35 31 33 30 5d 20 5b 48 31 27] [H15130] [H1
260d0 35 31 33 33 5d 20 5b 48 31 35 31 33 36 5d 0a 2a 5133] [H15136].*
260e0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e /.SQLITE_API con
260f0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
26100 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 _value_blob(sqli
26110 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c te3_value*);.SQL
26120 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
26130 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 te3_value_bytes(
26140 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
26150 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
26160 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 sqlite3_value_by
26170 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 tes16(sqlite3_va
26180 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 lue*);.SQLITE_AP
26190 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 I double sqlite3
261a0 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 _value_double(sq
261b0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 lite3_value*);.S
261c0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
261d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 lite3_value_int(
261e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
261f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 .SQLITE_API sqli
26200 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 te3_int64 sqlite
26210 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 3_value_int64(sq
26220 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 lite3_value*);.S
26230 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
26240 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 unsigned char *s
26250 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
26260 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t(sqlite3_value*
26270 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
26280 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
26290 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 3_value_text16(s
262a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
262b0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
262c0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 void *sqlite3_v
262d0 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 alue_text16le(sq
262e0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 lite3_value*);.S
262f0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
26300 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 void *sqlite3_va
26310 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c lue_text16be(sql
26320 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 ite3_value*);.SQ
26330 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
26340 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 ite3_value_type(
26350 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
26360 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
26370 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 sqlite3_value_nu
26380 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 meric_type(sqlit
26390 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a e3_value*);../*.
263a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 ** CAPI3REF: Obt
263b0 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 ain Aggregate Fu
263c0 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 7b nction Context {
263d0 48 31 36 32 31 30 7d 20 3c 53 32 30 32 30 30 3e H16210} <S20200>
263e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 .**.** The imple
263f0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67 67 mentation of agg
26400 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 regate SQL funct
26410 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20 72 6f ions use this ro
26420 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 utine to allocat
26430 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75 72 65 e.** a structure
26440 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 for storing the
26450 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 ir state..**.**
26460 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 The first time t
26470 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 he sqlite3_aggre
26480 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 72 gate_context() r
26490 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 outine is called
264a0 20 66 6f 72 20 61 0a 2a 2a 20 70 61 72 74 69 63 for a.** partic
264b0 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 2c 20 ular aggregate,
264c0 53 51 4c 69 74 65 20 61 6c 6c 6f 63 61 74 65 73 SQLite allocates
264d0 20 6e 42 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 nBytes of memor
264e0 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 y, zeroes out th
264f0 61 74 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 61 6e at.** memory, an
26500 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e d returns a poin
26510 74 65 72 20 74 6f 20 69 74 2e 20 4f 6e 20 73 65 ter to it. On se
26520 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 cond and subsequ
26530 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 ent calls to.**
26540 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
26550 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 e_context() for
26560 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 the same aggrega
26570 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64 65 te function inde
26580 78 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 x,.** the same b
26590 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 uffer is returne
265a0 64 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 d. The implement
265b0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 61 67 67 ation of the agg
265c0 72 65 67 61 74 65 20 63 61 6e 20 75 73 65 0a 2a regate can use.*
265d0 2a 20 74 68 65 20 72 65 74 75 72 6e 65 64 20 62 * the returned b
265e0 75 66 66 65 72 20 74 6f 20 61 63 63 75 6d 75 6c uffer to accumul
265f0 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 ate data..**.**
26600 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 SQLite automatic
26610 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 61 ally frees the a
26620 6c 6c 6f 63 61 74 65 64 20 62 75 66 66 65 72 20 llocated buffer
26630 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 when the aggrega
26640 74 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63 te.** query conc
26650 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ludes..**.** The
26660 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
26670 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 6f 70 should be a cop
26680 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c y of the.** [sql
26690 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 ite3_context | S
266a0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 QL function cont
266b0 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 ext] that is the
266c0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
266d0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 .** to the callb
266e0 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 ack routine that
266f0 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 implements the
26700 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 aggregate functi
26710 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 on..**.** This r
26720 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 outine must be c
26730 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 alled from the s
26740 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 ame thread in wh
26750 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 ich.** the aggre
26760 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f gate SQL functio
26770 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a n is running..**
26780 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
26790 3a 0a 2a 2a 20 5b 48 31 36 32 31 31 5d 20 5b 48 :.** [H16211] [H
267a0 31 36 32 31 33 5d 20 5b 48 31 36 32 31 35 5d 20 16213] [H16215]
267b0 5b 48 31 36 32 31 37 5d 0a 2a 2f 0a 53 51 4c 49 [H16217].*/.SQLI
267c0 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c TE_API void *sql
267d0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
267e0 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 ontext(sqlite3_c
267f0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 ontext*, int nBy
26800 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tes);../*.** CAP
26810 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 I3REF: User Data
26820 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b For Functions {
26830 48 31 36 32 34 30 7d 20 3c 53 32 30 32 30 30 3e H16240} <S20200>
26840 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
26850 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 e3_user_data() i
26860 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
26870 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 a copy of.** th
26880 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 e pointer that w
26890 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61 as the pUserData
268a0 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 parameter (the
268b0 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 5th parameter).*
268c0 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 * of the [sqlite
268d0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
268e0 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c n()].** and [sql
268f0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
26900 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e tion16()] routin
26910 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c es that original
26920 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 ly.** registered
26930 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
26940 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f defined functio
26950 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 n. {END}.**.** T
26960 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 his routine must
26970 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 be called from
26980 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 the same thread
26990 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 in which.** the
269a0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
269b0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 ned function is
269c0 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 running..**.** R
269d0 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
269e0 5b 48 31 36 32 34 33 5d 0a 2a 2f 0a 53 51 4c 49 [H16243].*/.SQLI
269f0 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c TE_API void *sql
26a00 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 ite3_user_data(s
26a10 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 qlite3_context*)
26a20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
26a30 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e F: Database Conn
26a40 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 ection For Funct
26a50 69 6f 6e 73 20 7b 48 31 36 32 35 30 7d 20 3c 53 ions {H16250} <S
26a60 36 30 36 30 30 3e 3c 53 32 30 32 30 30 3e 0a 2a 60600><S20200>.*
26a70 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
26a80 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 _context_db_hand
26a90 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 le() interface r
26aa0 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 eturns a copy of
26ab0 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 .** the pointer
26ac0 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 to the [database
26ad0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 connection] (th
26ae0 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 e 1st parameter)
26af0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 .** of the [sqli
26b00 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
26b10 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 ion()].** and [s
26b20 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
26b30 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 nction16()] rout
26b40 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e ines that origin
26b50 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 ally.** register
26b60 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ed the applicati
26b70 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on defined funct
26b80 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 ion..**.** Requi
26b90 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 rements:.** [H16
26ba0 32 35 33 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 253].*/.SQLITE_A
26bb0 50 49 20 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 PI sqlite3 *sqli
26bc0 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 te3_context_db_h
26bd0 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f andle(sqlite3_co
26be0 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ntext*);../*.**
26bf0 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 CAPI3REF: Functi
26c00 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 on Auxiliary Dat
26c10 61 20 7b 48 31 36 32 37 30 7d 20 3c 53 32 30 32 a {H16270} <S202
26c20 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 00>.**.** The fo
26c30 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 llowing two func
26c40 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 tions may be use
26c50 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 d by scalar SQL
26c60 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 functions to.**
26c70 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 associate metada
26c80 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 ta with argument
26c90 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 values. If the
26ca0 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 same value is pa
26cb0 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 ssed to.** multi
26cc0 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 ple invocations
26cd0 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 of the same SQL
26ce0 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 function during
26cf0 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c query execution,
26d00 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 under.** some c
26d10 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 ircumstances the
26d20 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 associated meta
26d30 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 data may be pres
26d40 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a erved. This may.
26d50 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 ** be used, for
26d60 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 example, to add
26d70 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 a regular-expres
26d80 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 sion matching sc
26d90 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e alar.** function
26da0 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 . The compiled v
26db0 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 ersion of the re
26dc0 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e gular expression
26dd0 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a is stored as.**
26de0 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 metadata associ
26df0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 53 51 ated with the SQ
26e00 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 L value passed a
26e10 73 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 s the regular ex
26e20 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 pression.** patt
26e30 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c ern. The compil
26e40 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 ed regular expre
26e50 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 ssion can be reu
26e60 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a sed on multiple.
26e70 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f ** invocations o
26e80 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 f the same funct
26e90 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 ion so that the
26ea0 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e original pattern
26eb0 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 string.** does
26ec0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 not need to be r
26ed0 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 ecompiled on eac
26ee0 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a h invocation..**
26ef0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
26f00 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e get_auxdata() in
26f10 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
26f20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
26f30 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 metadata.** ass
26f40 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73 ociated by the s
26f50 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 qlite3_set_auxda
26f60 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 ta() function wi
26f70 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d th the Nth argum
26f80 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 ent.** value to
26f90 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
26fa0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
26fb0 2e 20 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 . If no metadata
26fc0 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a has been ever.*
26fd0 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 * been set for t
26fe0 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 he Nth argument
26ff0 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c of the function,
27000 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 or if the corre
27010 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 sponding.** func
27020 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68 tion parameter h
27030 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 as changed since
27040 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 the meta-data w
27050 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 as set,.** then
27060 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 sqlite3_get_auxd
27070 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 20 ata() returns a
27080 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a NULL pointer..**
27090 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
270a0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e set_auxdata() in
270b0 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68 terface saves th
270c0 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f e metadata.** po
270d0 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20 inted to by its
270e0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 3rd parameter as
270f0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f the metadata fo
27100 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 r the N-th.** ar
27110 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 gument of the ap
27120 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
27130 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 d function. Sub
27140 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 sequent.** calls
27150 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f to sqlite3_get_
27160 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20 auxdata() might
27170 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61 return this data
27180 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e , if it has.** n
27190 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65 ot been destroye
271a0 64 2e 0a 2a 2a 20 49 66 20 69 74 20 69 73 20 6e d..** If it is n
271b0 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 ot NULL, SQLite
271c0 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 will invoke the
271d0 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 destructor.** fu
271e0 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 nction given by
271f0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 the 4th paramete
27200 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 r to sqlite3_set
27210 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a _auxdata() on.**
27220 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77 68 the metadata wh
27230 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e en the correspon
27240 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 ding function pa
27250 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a rameter changes.
27260 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53 ** or when the S
27270 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d QL statement com
27280 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65 pletes, whicheve
27290 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a r comes first..*
272a0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 *.** SQLite is f
272b0 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 ree to call the
272c0 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64 destructor and d
272d0 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 rop metadata on
272e0 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 any.** parameter
272f0 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e of any function
27300 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 54 at any time. T
27310 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 he only guarante
27320 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 e is that.** the
27330 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c destructor will
27340 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 be called befor
27350 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 e the metadata i
27360 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a s dropped..**.**
27370 20 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 In practice, me
27380 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72 tadata is preser
27390 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 ved between func
273a0 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a tion calls for.*
273b0 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 * expressions th
273c0 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 at are constant
273d0 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e at compile time.
273e0 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c This includes l
273f0 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 iteral.** values
27400 20 61 6e 64 20 53 51 4c 20 76 61 72 69 61 62 6c and SQL variabl
27410 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 es..**.** These
27420 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 routines must be
27430 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 called from the
27440 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 same thread in
27450 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c which.** the SQL
27460 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e function is run
27470 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 ning..**.** Requ
27480 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
27490 36 32 37 32 5d 20 5b 48 31 36 32 37 34 5d 20 5b 6272] [H16274] [
274a0 48 31 36 32 37 36 5d 20 5b 48 31 36 32 37 37 5d H16276] [H16277]
274b0 20 5b 48 31 36 32 37 38 5d 20 5b 48 31 36 32 37 [H16278] [H1627
274c0 39 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 9].*/.SQLITE_API
274d0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 void *sqlite3_g
274e0 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 et_auxdata(sqlit
274f0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 e3_context*, int
27500 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 N);.SQLITE_API
27510 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 void sqlite3_set
27520 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 _auxdata(sqlite3
27530 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e _context*, int N
27540 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a , void*, void (*
27550 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a )(void*));.../*.
27560 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e ** CAPI3REF: Con
27570 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 stants Defining
27580 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 Special Destruct
27590 6f 72 20 42 65 68 61 76 69 6f 72 20 7b 48 31 30 or Behavior {H10
275a0 32 38 30 7d 20 3c 53 33 30 31 30 30 3e 0a 2a 2a 280} <S30100>.**
275b0 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 .** These are sp
275c0 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 ecial values for
275d0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 the destructor
275e0 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69 that is passed i
275f0 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 n as the.** fina
27600 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f l argument to ro
27610 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c utines like [sql
27620 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 ite3_result_blob
27630 28 29 5d 2e 20 20 49 66 20 74 68 65 20 64 65 73 ()]. If the des
27640 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d tructor.** argum
27650 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 ent is SQLITE_ST
27660 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 ATIC, it means t
27670 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 hat the content
27680 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 pointer is const
27690 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 ant.** and will
276a0 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 never change. I
276b0 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 t does not need
276c0 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e to be destroyed.
276d0 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f The.** SQLITE_
276e0 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 TRANSIENT value
276f0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 means that the c
27700 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 ontent will like
27710 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 ly change in.**
27720 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 the near future
27730 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 and that SQLite
27740 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 should make its
27750 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 own private copy
27760 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 of.** the conte
27770 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e nt before return
27780 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 ing..**.** The t
27790 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 ypedef is necess
277a0 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 ary to work arou
277b0 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 nd problems in c
277c0 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f ertain.** C++ co
277d0 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69 mpilers. See ti
277e0 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 cket #2191..*/.t
277f0 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 ypedef void (*sq
27800 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 lite3_destructor
27810 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 _type)(void*);.#
27820 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 define SQLITE_ST
27830 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 ATIC ((sqli
27840 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 te3_destructor_t
27850 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 ype)0).#define S
27860 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 QLITE_TRANSIENT
27870 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 ((sqlite3_dest
27880 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a ructor_type)-1).
27890 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
278a0 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 Setting The Res
278b0 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 ult Of An SQL Fu
278c0 6e 63 74 69 6f 6e 20 7b 48 31 36 34 30 30 7d 20 nction {H16400}
278d0 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S20200>.**.** T
278e0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
278f0 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46 e used by the xF
27900 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 unc or xFinal ca
27910 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 llbacks that.**
27920 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 implement SQL fu
27930 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 nctions and aggr
27940 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 egates. See.**
27950 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
27960 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 function()] and
27970 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
27980 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a function16()].**
27990 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 for additional
279a0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a information..**.
279b0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f ** These functio
279c0 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 ns work very muc
279d0 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 h like the [para
279e0 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 meter binding] f
279f0 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 amily of.** func
27a00 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 tions used to bi
27a10 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 nd values to hos
27a20 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 t parameters in
27a30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
27a40 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f nts..** Refer to
27a50 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 the [SQL parame
27a60 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 ter] documentati
27a70 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 on for additiona
27a80 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a l information..*
27a90 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
27aa0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 _result_blob() i
27ab0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 nterface sets th
27ac0 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a e result from.**
27ad0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d an application-
27ae0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
27af0 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 to be the BLOB
27b00 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 whose content is
27b10 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 pointed.** to b
27b20 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 y the second par
27b30 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 ameter and which
27b40 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 is N bytes long
27b50 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a where N is the.
27b60 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 ** third paramet
27b70 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 er..**.** The sq
27b80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 lite3_result_zer
27b90 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 oblob() interfac
27ba0 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c es set the resul
27bb0 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c t of.** the appl
27bc0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
27bd0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 function to be a
27be0 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 BLOB containing
27bf0 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 all zero.** byt
27c00 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 es and N bytes i
27c10 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 n size, where N
27c20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 is the value of
27c30 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 the 2nd paramete
27c40 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c r..**.** The sql
27c50 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 ite3_result_doub
27c60 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 le() interface s
27c70 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 ets the result f
27c80 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 rom.** an applic
27c90 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
27ca0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 nction to be a f
27cb0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 loating point va
27cc0 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a lue specified.**
27cd0 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 by its 2nd argu
27ce0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ment..**.** The
27cf0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
27d00 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 rror() and sqlit
27d10 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 e3_result_error1
27d20 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 6() functions.**
27d30 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 cause the imple
27d40 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 mented SQL funct
27d50 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 ion to throw an
27d60 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 53 51 exception..** SQ
27d70 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 Lite uses the st
27d80 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 ring pointed to
27d90 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 by the.** 2nd pa
27da0 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 rameter of sqlit
27db0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 e3_result_error(
27dc0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 ) or sqlite3_res
27dd0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a ult_error16().**
27de0 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 as the text of
27df0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 an error message
27e00 2e 20 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 . SQLite interp
27e10 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a rets the error.*
27e20 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 * message string
27e30 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 from sqlite3_re
27e40 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 sult_error() as
27e50 55 54 46 2d 38 2e 20 53 51 4c 69 74 65 0a 2a 2a UTF-8. SQLite.**
27e60 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 interprets the
27e70 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 string from sqli
27e80 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
27e90 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 16() as UTF-16 i
27ea0 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 n native.** byte
27eb0 20 6f 72 64 65 72 2e 20 20 49 66 20 74 68 65 20 order. If the
27ec0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
27ed0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c to sqlite3_resul
27ee0 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 t_error().** or
27ef0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
27f00 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 rror16() is nega
27f10 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 tive then SQLite
27f20 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 takes as the er
27f30 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 ror.** message a
27f40 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 ll text up throu
27f50 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 gh the first zer
27f60 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 o character..**
27f70 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 If the third par
27f80 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
27f90 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 3_result_error()
27fa0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 or.** sqlite3_r
27fb0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 esult_error16()
27fc0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 is non-negative
27fd0 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 then SQLite take
27fe0 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 s that many.** b
27ff0 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 ytes (not charac
28000 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 ters) from the 2
28010 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 nd parameter as
28020 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 the error messag
28030 65 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 e..** The sqlite
28040 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 3_result_error()
28050 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 and sqlite3_res
28060 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a ult_error16().**
28070 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 routines make a
28080 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 private copy of
28090 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 the error messa
280a0 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a ge text before.*
280b0 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 * they return.
280c0 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 Hence, the calli
280d0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 ng function can
280e0 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a deallocate or.**
280f0 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 modify the text
28100 20 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75 after they retu
28110 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e rn without harm.
28120 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
28130 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 result_error_cod
28140 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 e() function cha
28150 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 nges the error c
28160 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 ode.** returned
28170 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 by SQLite as a r
28180 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f esult of an erro
28190 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e r in a function.
281a0 20 20 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a By default,.**
281b0 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 the error code
281c0 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e is SQLITE_ERROR.
281d0 20 20 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 A subsequent c
281e0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 all to sqlite3_r
281f0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a esult_error().**
28200 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 or sqlite3_resu
28210 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 lt_error16() res
28220 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f ets the error co
28230 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 de to SQLITE_ERR
28240 4f 52 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 OR..**.** The sq
28250 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f lite3_result_too
28260 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 big() interface
28270 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f causes SQLite to
28280 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a throw an error.
28290 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 ** indicating th
282a0 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 at a string or B
282b0 4c 4f 42 20 69 73 20 74 6f 20 6c 6f 6e 67 20 74 LOB is to long t
282c0 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a o represent..**.
282d0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 ** The sqlite3_r
282e0 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e esult_nomem() in
282f0 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 terface causes S
28300 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 QLite to throw a
28310 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 n error.** indic
28320 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d ating that a mem
28330 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 ory allocation f
28340 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ailed..**.** The
28350 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
28360 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 int() interface
28370 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 sets the return
28380 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 value.** of the
28390 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
283a0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 ned function to
283b0 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 be the 32-bit si
283c0 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 gned integer.**
283d0 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 value given in t
283e0 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e he 2nd argument.
283f0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
28400 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 result_int64() i
28410 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 nterface sets th
28420 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a e return value.*
28430 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 * of the applica
28440 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
28450 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 ction to be the
28460 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 64-bit signed in
28470 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 teger.** value g
28480 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 iven in the 2nd
28490 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 argument..**.**
284a0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
284b0 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 lt_null() interf
284c0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 ace sets the ret
284d0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 urn value.** of
284e0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
284f0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
28500 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a to be NULL..**.
28510 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 ** The sqlite3_r
28520 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 esult_text(), sq
28530 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
28540 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 t16(),.** sqlite
28550 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 3_result_text16l
28560 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 e(), and sqlite3
28570 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 _result_text16be
28580 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a () interfaces.**
28590 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 set the return
285a0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 value of the app
285b0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
285c0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a function to be.
285d0 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 ** a text string
285e0 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73 which is repres
285f0 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 ented as UTF-8,
28600 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 UTF-16 native by
28610 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 te order,.** UTF
28620 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 -16 little endia
28630 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 n, or UTF-16 big
28640 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 endian, respect
28650 69 76 65 6c 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 ively..** SQLite
28660 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 takes the text
28670 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 result from the
28680 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d application from
28690 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 .** the 2nd para
286a0 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c meter of the sql
286b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
286c0 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a * interfaces..**
286d0 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 If the 3rd para
286e0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c meter to the sql
286f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
28700 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 * interfaces.**
28710 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 is negative, the
28720 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 n SQLite takes r
28730 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 esult text from
28740 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 the 2nd paramete
28750 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 r.** through the
28760 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 first zero char
28770 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 acter..** If the
28780 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 3rd parameter t
28790 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 o the sqlite3_re
287a0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 sult_text* inter
287b0 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d faces.** is non-
287c0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 negative, then a
287d0 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f s many bytes (no
287e0 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 t characters) of
287f0 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 the text.** poi
28800 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 nted to by the 2
28810 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 nd parameter are
28820 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 taken as the ap
28830 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
28840 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 d.** function re
28850 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 sult..** If the
28860 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 4th parameter to
28870 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 the sqlite3_res
28880 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 ult_text* interf
28890 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 aces.** or sqlit
288a0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 e3_result_blob i
288b0 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 s a non-NULL poi
288c0 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 nter, then SQLit
288d0 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 e calls that.**
288e0 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 function as the
288f0 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 destructor on th
28900 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 e text or BLOB r
28910 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 esult when it ha
28920 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 s.** finished us
28930 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e ing that result.
28940 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 .** If the 4th p
28950 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
28960 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
28970 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 ext* interfaces
28980 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 or to.** sqlite3
28990 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 _result_blob is
289a0 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 the special cons
289b0 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 tant SQLITE_STAT
289c0 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a IC, then SQLite.
289d0 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 ** assumes that
289e0 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 the text or BLOB
289f0 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f result is in co
28a00 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 nstant space and
28a10 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 does not.** cop
28a20 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 y the content of
28a30 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e the parameter n
28a40 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 or call a destru
28a50 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 ctor on the cont
28a60 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 ent.** when it h
28a70 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e as finished usin
28a80 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a g that result..*
28a90 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72 * If the 4th par
28aa0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 ameter to the sq
28ab0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
28ac0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a t* interfaces.**
28ad0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 or sqlite3_resu
28ae0 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 lt_blob is the s
28af0 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 pecial constant
28b00 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 SQLITE_TRANSIENT
28b10 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 .** then SQLite
28b20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 makes a copy of
28b30 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 the result into
28b40 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 space obtained f
28b50 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c rom.** from [sql
28b60 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 ite3_malloc()] b
28b70 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 efore it returns
28b80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
28b90 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 te3_result_value
28ba0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 () interface set
28bb0 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a s the result of.
28bc0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ** the applicati
28bd0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
28be0 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 ion to be a copy
28bf0 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 the.** [unprote
28c00 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
28c10 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 ue] object speci
28c20 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 fied by the 2nd
28c30 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 0a parameter. The.
28c40 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c ** sqlite3_resul
28c50 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 t_value() interf
28c60 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 ace makes a copy
28c70 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
28c80 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 _value].** so th
28c90 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f at the [sqlite3_
28ca0 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 value] specified
28cb0 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 in the paramete
28cc0 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a r may change or.
28cd0 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 ** be deallocate
28ce0 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f d after sqlite3_
28cf0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 result_value() r
28d00 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 eturns without h
28d10 61 72 6d 2e 0a 2a 2a 20 41 20 5b 70 72 6f 74 65 arm..** A [prote
28d20 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
28d30 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 ue] object may a
28d40 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68 lways be used wh
28d50 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f ere an.** [unpro
28d60 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
28d70 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 alue] object is
28d80 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 required, so eit
28d90 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b her.** kind of [
28da0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
28db0 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 bject can be use
28dc0 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 d with this inte
28dd0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 rface..**.** If
28de0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 these routines a
28df0 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 re called from w
28e00 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 ithin the differ
28e10 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 ent thread.** th
28e20 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 an the one conta
28e30 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 ining the applic
28e40 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
28e50 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 nction that rece
28e60 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c ived.** the [sql
28e70 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f ite3_context] po
28e80 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c inter, the resul
28e90 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 ts are undefined
28ea0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
28eb0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 34 30 33 ents:.** [H16403
28ec0 5d 20 5b 48 31 36 34 30 36 5d 20 5b 48 31 36 34 ] [H16406] [H164
28ed0 30 39 5d 20 5b 48 31 36 34 31 32 5d 20 5b 48 31 09] [H16412] [H1
28ee0 36 34 31 35 5d 20 5b 48 31 36 34 31 38 5d 20 5b 6415] [H16418] [
28ef0 48 31 36 34 32 31 5d 20 5b 48 31 36 34 32 34 5d H16421] [H16424]
28f00 0a 2a 2a 20 5b 48 31 36 34 32 37 5d 20 5b 48 31 .** [H16427] [H1
28f10 36 34 33 30 5d 20 5b 48 31 36 34 33 33 5d 20 5b 6430] [H16433] [
28f20 48 31 36 34 33 36 5d 20 5b 48 31 36 34 33 39 5d H16436] [H16439]
28f30 20 5b 48 31 36 34 34 32 5d 20 5b 48 31 36 34 34 [H16442] [H1644
28f40 35 5d 20 5b 48 31 36 34 34 38 5d 0a 2a 2a 20 5b 5] [H16448].** [
28f50 48 31 36 34 35 31 5d 20 5b 48 31 36 34 35 34 5d H16451] [H16454]
28f60 20 5b 48 31 36 34 35 37 5d 20 5b 48 31 36 34 36 [H16457] [H1646
28f70 30 5d 20 5b 48 31 36 34 36 33 5d 0a 2a 2f 0a 53 0] [H16463].*/.S
28f80 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
28f90 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c qlite3_result_bl
28fa0 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ob(sqlite3_conte
28fb0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a xt*, const void*
28fc0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 , int, void(*)(v
28fd0 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 oid*));.SQLITE_A
28fe0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f PI void sqlite3_
28ff0 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 result_double(sq
29000 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
29010 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f double);.SQLITE_
29020 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 API void sqlite3
29030 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 _result_error(sq
29040 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
29050 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 const char*, int
29060 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f );.SQLITE_API vo
29070 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
29080 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 t_error16(sqlite
29090 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 3_context*, cons
290a0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 t void*, int);.S
290b0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
290c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
290d0 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 ror_toobig(sqlit
290e0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 e3_context*);.SQ
290f0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 LITE_API void sq
29100 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
29110 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 or_nomem(sqlite3
29120 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 _context*);.SQLI
29130 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 TE_API void sqli
29140 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
29150 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f _code(sqlite3_co
29160 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 ntext*, int);.SQ
29170 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 LITE_API void sq
29180 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 lite3_result_int
29190 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
291a0 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f *, int);.SQLITE_
291b0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 API void sqlite3
291c0 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 _result_int64(sq
291d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
291e0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a sqlite3_int64);.
291f0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
29200 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e sqlite3_result_n
29210 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ull(sqlite3_cont
29220 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 ext*);.SQLITE_AP
29230 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 I void sqlite3_r
29240 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 esult_text(sqlit
29250 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e e3_context*, con
29260 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 st char*, int, v
29270 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
29280 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
29290 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
292a0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f ext16(sqlite3_co
292b0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f ntext*, const vo
292c0 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a id*, int, void(*
292d0 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 )(void*));.SQLIT
292e0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 E_API void sqlit
292f0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 e3_result_text16
29300 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 le(sqlite3_conte
29310 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a xt*, const void*
29320 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f , int,void(*)(vo
29330 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 id*));.SQLITE_AP
29340 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 I void sqlite3_r
29350 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 esult_text16be(s
29360 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
29370 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
29380 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 t,void(*)(void*)
29390 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f );.SQLITE_API vo
293a0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
293b0 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f t_value(sqlite3_
293c0 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 context*, sqlite
293d0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 3_value*);.SQLIT
293e0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 E_API void sqlit
293f0 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c e3_result_zerobl
29400 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ob(sqlite3_conte
29410 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a xt*, int n);../*
29420 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
29430 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 fine New Collati
29440 6e 67 20 53 65 71 75 65 6e 63 65 73 20 7b 48 31 ng Sequences {H1
29450 36 36 30 30 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 6600} <S20300>.*
29460 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 *.** These funct
29470 69 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f ions are used to
29480 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 add new collati
29490 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20 on sequences to
294a0 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 the.** [database
294b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 connection] spe
294c0 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69 cified as the fi
294d0 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a rst argument..**
294e0 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 .** The name of
294f0 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f the new collatio
29500 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 73 70 n sequence is sp
29510 65 63 69 66 69 65 64 20 61 73 20 61 20 55 54 46 ecified as a UTF
29520 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 -8 string.** for
29530 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
29540 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 collation() and
29550 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
29560 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a ollation_v2().**
29570 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 and a UTF-16 st
29580 72 69 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33 ring for sqlite3
29590 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
295a0 6e 31 36 28 29 2e 20 49 6e 20 61 6c 6c 20 63 61 n16(). In all ca
295b0 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 ses.** the name
295c0 69 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 is passed as the
295d0 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e second function
295e0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a argument..**.**
295f0 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d The third argum
29600 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f ent may be one o
29610 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 f the constants
29620 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a [SQLITE_UTF8],.*
29630 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c * [SQLITE_UTF16L
29640 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 E], or [SQLITE_U
29650 54 46 31 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 TF16BE], indicat
29660 69 6e 67 20 74 68 61 74 20 74 68 65 20 75 73 65 ing that the use
29670 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f r-supplied.** ro
29680 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 74 6f utine expects to
29690 20 62 65 20 70 61 73 73 65 64 20 70 6f 69 6e 74 be passed point
296a0 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 65 ers to strings e
296b0 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 ncoded using UTF
296c0 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 -8,.** UTF-16 li
296d0 74 74 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20 ttle-endian, or
296e0 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 UTF-16 big-endia
296f0 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e n, respectively.
29700 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 The.** third ar
29710 67 75 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 gument might als
29720 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 o be [SQLITE_UTF
29730 31 36 5d 20 74 6f 20 69 6e 64 69 63 61 74 65 20 16] to indicate
29740 74 68 61 74 20 74 68 65 20 72 6f 75 74 69 6e 65 that the routine
29750 0a 2a 2a 20 65 78 70 65 63 74 73 20 70 6f 69 6e .** expects poin
29760 74 65 72 73 20 74 6f 20 62 65 20 55 54 46 2d 31 ters to be UTF-1
29770 36 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 6 strings in the
29780 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 native byte ord
29790 65 72 2c 20 6f 72 20 74 68 65 0a 2a 2a 20 61 72 er, or the.** ar
297a0 67 75 6d 65 6e 74 20 63 61 6e 20 62 65 20 5b 53 gument can be [S
297b0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 QLITE_UTF16_ALIG
297c0 4e 45 44 5d 20 69 66 20 74 68 65 0a 2a 2a 20 74 NED] if the.** t
297d0 68 65 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 he routine expec
297e0 74 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 31 ts pointers to 1
297f0 36 2d 62 69 74 20 77 6f 72 64 20 61 6c 69 67 6e 6-bit word align
29800 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 ed strings.** of
29810 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e UTF-16 in the n
29820 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
29830 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 ..**.** A pointe
29840 72 20 74 6f 20 74 68 65 20 75 73 65 72 20 73 75 r to the user su
29850 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d pplied routine m
29860 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 ust be passed as
29870 20 74 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 the fifth.** ar
29880 67 75 6d 65 6e 74 2e 20 20 49 66 20 69 74 20 69 gument. If it i
29890 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20 s NULL, this is
298a0 74 68 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65 the same as dele
298b0 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69 ting the collati
298c0 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28 on.** sequence (
298d0 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 so that SQLite c
298e0 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e annot call it an
298f0 79 6d 6f 72 65 29 2e 0a 2a 2a 20 45 61 63 68 20 ymore)..** Each
29900 74 69 6d 65 20 74 68 65 20 61 70 70 6c 69 63 61 time the applica
29910 74 69 6f 6e 20 73 75 70 70 6c 69 65 64 20 66 75 tion supplied fu
29920 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 nction is invoke
29930 64 2c 20 69 74 20 69 73 20 70 61 73 73 65 64 0a d, it is passed.
29940 2a 2a 20 61 73 20 69 74 73 20 66 69 72 73 74 20 ** as its first
29950 70 61 72 61 6d 65 74 65 72 20 61 20 63 6f 70 79 parameter a copy
29960 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 61 of the void* pa
29970 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 ssed as the four
29980 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 th argument.** t
29990 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 o sqlite3_create
299a0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 20 _collation() or
299b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
299c0 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a ollation16()..**
299d0 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e .** The remainin
299e0 67 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 g arguments to t
299f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 he application-s
29a00 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 upplied routine
29a10 61 72 65 20 74 77 6f 20 73 74 72 69 6e 67 73 2c are two strings,
29a20 0a 2a 2a 20 65 61 63 68 20 72 65 70 72 65 73 65 .** each represe
29a30 6e 74 65 64 20 62 79 20 61 20 28 6c 65 6e 67 74 nted by a (lengt
29a40 68 2c 20 64 61 74 61 29 20 70 61 69 72 20 61 6e h, data) pair an
29a50 64 20 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 d encoded in the
29a60 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 encoding.** tha
29a70 74 20 77 61 73 20 70 61 73 73 65 64 20 61 73 20 t was passed as
29a80 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 the third argume
29a90 6e 74 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c nt when the coll
29aa0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 ation sequence w
29ab0 61 73 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 as.** registered
29ac0 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20 61 70 70 . {END} The app
29ad0 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 lication defined
29ae0 20 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69 collation routi
29af0 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 ne should.** ret
29b00 75 72 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 urn negative, ze
29b10 72 6f 20 6f 72 20 70 6f 73 69 74 69 76 65 20 69 ro or positive i
29b20 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69 f the first stri
29b30 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c ng is less than,
29b40 0a 2a 2a 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 .** equal to, or
29b50 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 greater than th
29b60 65 20 73 65 63 6f 6e 64 20 73 74 72 69 6e 67 2e e second string.
29b70 20 69 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d i.e. (STRING1 -
29b80 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a STRING2)..**.**
29b90 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 The sqlite3_cre
29ba0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 ate_collation_v2
29bb0 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 () works like sq
29bc0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
29bd0 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 65 lation().** exce
29be0 70 74 20 74 68 61 74 20 69 74 20 74 61 6b 65 73 pt that it takes
29bf0 20 61 6e 20 65 78 74 72 61 20 61 72 67 75 6d 65 an extra argume
29c00 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 64 65 nt which is a de
29c10 73 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 structor for.**
29c20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 the collation.
29c30 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 The destructor i
29c40 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 s called when th
29c50 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a e collation is.*
29c60 2a 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 * destroyed and
29c70 69 73 20 70 61 73 73 65 64 20 61 20 63 6f 70 79 is passed a copy
29c80 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 of the fourth p
29c90 61 72 61 6d 65 74 65 72 20 76 6f 69 64 2a 20 70 arameter void* p
29ca0 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65 ointer.** of the
29cb0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
29cc0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a collation_v2()..
29cd0 2a 2a 20 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 ** Collations ar
29ce0 65 20 64 65 73 74 72 6f 79 65 64 20 77 68 65 6e e destroyed when
29cf0 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 they are overri
29d00 64 64 65 6e 20 62 79 20 6c 61 74 65 72 20 63 61 dden by later ca
29d10 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 63 6f lls to the.** co
29d20 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e llation creation
29d30 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 functions or wh
29d40 65 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 en the [database
29d50 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 connection] is
29d60 63 6c 6f 73 65 64 0a 2a 2a 20 75 73 69 6e 67 20 closed.** using
29d70 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 [sqlite3_close()
29d80 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 ]..**.** See als
29d90 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c o: [sqlite3_col
29da0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d lation_needed()]
29db0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f and [sqlite3_co
29dc0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 llation_needed16
29dd0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 ()]..**.** Requi
29de0 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 rements:.** [H16
29df0 36 30 33 5d 20 5b 48 31 36 36 30 34 5d 20 5b 48 603] [H16604] [H
29e00 31 36 36 30 36 5d 20 5b 48 31 36 36 30 39 5d 20 16606] [H16609]
29e10 5b 48 31 36 36 31 32 5d 20 5b 48 31 36 36 31 35 [H16612] [H16615
29e20 5d 20 5b 48 31 36 36 31 38 5d 20 5b 48 31 36 36 ] [H16618] [H166
29e30 32 31 5d 0a 2a 2a 20 5b 48 31 36 36 32 34 5d 20 21].** [H16624]
29e40 5b 48 31 36 36 32 37 5d 20 5b 48 31 36 36 33 30 [H16627] [H16630
29e50 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
29e60 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 int sqlite3_crea
29e70 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 te_collation(.
29e80 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e sqlite3*, . con
29e90 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
29ea0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c . int eTextRep,
29eb0 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 . void*,. int
29ec0 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 (*xCompare)(void
29ed0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 *,int,const void
29ee0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 *,int,const void
29ef0 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 *).);.SQLITE_API
29f00 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 int sqlite3_cre
29f10 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 ate_collation_v2
29f20 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 (. sqlite3*, .
29f30 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
29f40 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 me, . int eText
29f50 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 Rep, . void*,.
29f60 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 int(*xCompare)(
29f70 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 void*,int,const
29f80 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 void*,int,const
29f90 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a void*),. void(*
29fa0 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 xDestroy)(void*)
29fb0 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .);.SQLITE_API i
29fc0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 nt sqlite3_creat
29fd0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 e_collation16(.
29fe0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f sqlite3*, . co
29ff0 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c nst void *zName,
2a000 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c . int eTextRep,
2a010 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 . void*,. int
2a020 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 (*xCompare)(void
2a030 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 *,int,const void
2a040 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 *,int,const void
2a050 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 *).);../*.** CAP
2a060 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e I3REF: Collation
2a070 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b Needed Callback
2a080 73 20 7b 48 31 36 37 30 30 7d 20 3c 53 32 30 33 s {H16700} <S203
2a090 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 00>.**.** To avo
2a0a0 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 id having to reg
2a0b0 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 ister all collat
2a0c0 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 ion sequences be
2a0d0 66 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a fore a database.
2a0e0 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 ** can be used,
2a0f0 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 a single callbac
2a100 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 k function may b
2a110 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 e registered wit
2a120 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 h the.** [databa
2a130 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 se connection] t
2a140 6f 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e o be called when
2a150 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 ever an undefine
2a160 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 d collation.** s
2a170 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 equence is requi
2a180 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 red..**.** If th
2a190 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 e function is re
2a1a0 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 gistered using t
2a1b0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 he sqlite3_colla
2a1c0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 tion_needed() AP
2a1d0 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 I,.** then it is
2a1e0 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 passed the name
2a1f0 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 s of undefined c
2a200 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 ollation sequenc
2a210 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a es as strings.**
2a220 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d encoded in UTF-
2a230 38 2e 20 7b 48 31 36 37 30 33 7d 20 49 66 20 73 8. {H16703} If s
2a240 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
2a250 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75 _needed16() is u
2a260 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 sed,.** the name
2a270 73 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 s are passed as
2a280 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e UTF-16 in machin
2a290 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 e native byte or
2a2a0 64 65 72 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 der..** A call t
2a2b0 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f o either functio
2a2c0 6e 20 72 65 70 6c 61 63 65 73 20 61 6e 79 20 65 n replaces any e
2a2d0 78 69 73 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b xisting callback
2a2e0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 ..**.** When the
2a2f0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
2a300 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 oked, the first
2a310 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 argument passed
2a320 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 is a copy.** of
2a330 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d the second argum
2a340 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 ent to sqlite3_c
2a350 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 ollation_needed(
2a360 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ) or.** sqlite3_
2a370 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 collation_needed
2a380 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 16(). The secon
2a390 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 d argument is th
2a3a0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f e database.** co
2a3b0 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 nnection. The t
2a3c0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 hird argument is
2a3d0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f one of [SQLITE_
2a3e0 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 UTF8], [SQLITE_U
2a3f0 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b TF16BE],.** or [
2a400 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c SQLITE_UTF16LE],
2a410 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 indicating the
2a420 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 most desirable f
2a430 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 orm of the colla
2a440 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 tion.** sequence
2a450 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 function requir
2a460 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 ed. The fourth
2a470 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
2a480 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 name of the.**
2a490 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 required collati
2a4a0 6f 6e 20 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a on sequence..**.
2a4b0 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 ** The callback
2a4c0 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 function should
2a4d0 72 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73 register the des
2a4e0 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 ired collation u
2a4f0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 sing.** [sqlite3
2a500 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
2a510 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 n()], [sqlite3_c
2a520 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 reate_collation1
2a530 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 6()], or.** [sql
2a540 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
2a550 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a ation_v2()]..**.
2a560 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
2a570 0a 2a 2a 20 5b 48 31 36 37 30 32 5d 20 5b 48 31 .** [H16702] [H1
2a580 36 37 30 34 5d 20 5b 48 31 36 37 30 36 5d 0a 2a 6704] [H16706].*
2a590 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
2a5a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 sqlite3_collati
2a5b0 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c on_needed(. sql
2a5c0 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c ite3*, . void*,
2a5d0 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 . void(*)(void
2a5e0 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 *,sqlite3*,int e
2a5f0 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 TextRep,const ch
2a600 61 72 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 ar*).);.SQLITE_A
2a610 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 PI int sqlite3_c
2a620 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 ollation_needed1
2a630 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 6(. sqlite3*, .
2a640 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 void*,. void(
2a650 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 *)(void*,sqlite3
2a660 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 *,int eTextRep,c
2a670 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a onst void*).);..
2a680 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 /*.** Specify th
2a690 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 e key for an enc
2a6a0 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e rypted database.
2a6b0 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 This routine s
2a6c0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c hould be.** call
2a6d0 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73 ed right after s
2a6e0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a qlite3_open()..*
2a6f0 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f *.** The code to
2a700 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 implement this
2a710 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c API is not avail
2a720 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c able in the publ
2a730 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 ic release.** of
2a740 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 SQLite..*/.SQLI
2a750 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
2a760 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 e3_key(. sqlite
2a770 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
2a780 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 /* Data
2a790 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 base to be rekey
2a7a0 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f ed */. const vo
2a7b0 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b id *pKey, int nK
2a7c0 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 ey /* The ke
2a7d0 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 y */.);../*.** C
2a7e0 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e hange the key on
2a7f0 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 an open databas
2a800 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65 e. If the curre
2a810 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e nt database is n
2a820 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c ot.** encrypted,
2a830 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 this routine wi
2a840 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 ll encrypt it.
2a850 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e If pNew==0 or nN
2a860 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 ew==0, the.** da
2a870 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70 tabase is decryp
2a880 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 ted..**.** The c
2a890 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 ode to implement
2a8a0 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 this API is not
2a8b0 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 available in th
2a8c0 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 e public release
2a8d0 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a .** of SQLite..*
2a8e0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
2a8f0 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a sqlite3_rekey(.
2a900 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
2a910 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2a920 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 /* Database to
2a930 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 be rekeyed */.
2a940 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 const void *pKey
2a950 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f , int nKey /
2a960 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f * The new key */
2a970 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
2a980 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 REF: Suspend Exe
2a990 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f cution For A Sho
2a9a0 72 74 20 54 69 6d 65 20 7b 48 31 30 35 33 30 7d rt Time {H10530}
2a9b0 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 <S40410>.**.**
2a9c0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 The sqlite3_slee
2a9d0 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 p() function cau
2a9e0 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 ses the current
2a9f0 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e thread to suspen
2aa00 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 d execution.** f
2aa10 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 or at least a nu
2aa20 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 mber of millisec
2aa30 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69 onds specified i
2aa40 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e n its parameter.
2aa50 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 .**.** If the op
2aa60 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 erating system d
2aa70 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 oes not support
2aa80 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77 sleep requests w
2aa90 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f ith.** milliseco
2aaa0 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 nd time resoluti
2aab0 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d on, then the tim
2aac0 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 e will be rounde
2aad0 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e d up to.** the n
2aae0 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 earest second. T
2aaf0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c he number of mil
2ab00 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 liseconds of sle
2ab10 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 ep actually.** r
2ab20 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 equested from th
2ab30 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 e operating syst
2ab40 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a em is returned..
2ab50 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 **.** SQLite imp
2ab60 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74 lements this int
2ab70 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e erface by callin
2ab80 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a g the xSleep().*
2ab90 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 * method of the
2aba0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 default [sqlite3
2abb0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a _vfs] object..**
2abc0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
2abd0 3a 20 5b 48 31 30 35 33 33 5d 20 5b 48 31 30 35 : [H10533] [H105
2abe0 33 36 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 36].*/.SQLITE_AP
2abf0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c I int sqlite3_sl
2ac00 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a eep(int);../*.**
2ac10 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 CAPI3REF: Name
2ac20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f Of The Folder Ho
2ac30 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 lding Temporary
2ac40 46 69 6c 65 73 20 7b 48 31 30 33 31 30 7d 20 3c Files {H10310} <
2ac50 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 49 66 S20000>.**.** If
2ac60 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 this global var
2ac70 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f iable is made to
2ac80 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 point to a stri
2ac90 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 ng which is.** t
2aca0 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c he name of a fol
2acb0 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 der (a.k.a. dire
2acc0 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c ctory), then all
2acd0 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 temporary files
2ace0 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 .** created by S
2acf0 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 70 6c QLite will be pl
2ad00 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 aced in that dir
2ad10 65 63 74 6f 72 79 2e 20 20 49 66 20 74 68 69 73 ectory. If this
2ad20 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 variable.** is
2ad30 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 a NULL pointer,
2ad40 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66 then SQLite perf
2ad50 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f orms a search fo
2ad60 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 r an appropriate
2ad70 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 .** temporary fi
2ad80 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a le directory..**
2ad90 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 .** It is not sa
2ada0 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f fe to read or mo
2adb0 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 dify this variab
2adc0 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 le in more than
2add0 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 one.** thread at
2ade0 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20 a time. It is
2adf0 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 not safe to read
2ae00 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 or modify this
2ae10 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 variable.** if a
2ae20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
2ae30 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 ction] is being
2ae40 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65 used at the same
2ae50 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72 time in a separ
2ae60 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a ate.** thread..*
2ae70 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 * It is intended
2ae80 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 that this varia
2ae90 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a ble be set once.
2aea0 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 ** as part of pr
2aeb0 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 ocess initializa
2aec0 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 tion and before
2aed0 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 any SQLite inter
2aee0 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 face.** routines
2aef0 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 have been calle
2af00 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 d and that this
2af10 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 variable remain
2af20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 unchanged.** the
2af30 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 reafter..**.** T
2af40 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 he [temp_store_d
2af50 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d irectory pragma]
2af60 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73 may modify this
2af70 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61 variable and ca
2af80 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 use.** it to poi
2af90 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 nt to memory obt
2afa0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 ained from [sqli
2afb0 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 46 75 te3_malloc]. Fu
2afc0 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 rthermore,.** th
2afd0 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 e [temp_store_di
2afe0 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 rectory pragma]
2aff0 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73 20 74 always assumes t
2b000 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a hat any string.*
2b010 2a 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 * that this vari
2b020 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 able points to i
2b030 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 s held in memory
2b040 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a obtained from .
2b050 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c ** [sqlite3_mall
2b060 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67 oc] and the prag
2b070 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 ma may attempt t
2b080 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f o free that memo
2b090 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c ry.** using [sql
2b0a0 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 ite3_free]..** H
2b0b0 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20 76 61 ence, if this va
2b0c0 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 riable is modifi
2b0d0 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74 ed directly, eit
2b0e0 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65 her it should be
2b0f0 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 .** made NULL or
2b100 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 made to point t
2b110 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 o memory obtaine
2b120 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
2b130 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c malloc].** or el
2b140 73 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 se the use of th
2b150 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 e [temp_store_di
2b160 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 rectory pragma]
2b170 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65 should be avoide
2b180 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 d..*/.SQLITE_API
2b190 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 SQLITE_EXTERN c
2b1a0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d har *sqlite3_tem
2b1b0 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a p_directory;../*
2b1c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 .** CAPI3REF: Te
2b1d0 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d st For Auto-Comm
2b1e0 69 74 20 4d 6f 64 65 20 7b 48 31 32 39 33 30 7d it Mode {H12930}
2b1f0 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 <S60200>.** KEY
2b200 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d WORDS: {autocomm
2b210 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 it mode}.**.** T
2b220 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 he sqlite3_get_a
2b230 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 utocommit() inte
2b240 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f rface returns no
2b250 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 n-zero or.** zer
2b260 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64 o if the given d
2b270 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2b280 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 on is or is not
2b290 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f in autocommit mo
2b2a0 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 de,.** respectiv
2b2b0 65 6c 79 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74 ely. Autocommit
2b2c0 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64 mode is on by d
2b2d0 65 66 61 75 6c 74 2e 0a 2a 2a 20 41 75 74 6f 63 efault..** Autoc
2b2e0 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 ommit mode is di
2b2f0 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47 sabled by a [BEG
2b300 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a IN] statement..*
2b310 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 * Autocommit mod
2b320 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 e is re-enabled
2b330 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 by a [COMMIT] or
2b340 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a [ROLLBACK]..**.
2b350 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 ** If certain ki
2b360 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 nds of errors oc
2b370 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 cur on a stateme
2b380 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 nt within a mult
2b390 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 i-statement.** t
2b3a0 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f ransaction (erro
2b3b0 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 rs including [SQ
2b3c0 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c LITE_FULL], [SQL
2b3d0 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b ITE_IOERR],.** [
2b3e0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b SQLITE_NOMEM], [
2b3f0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e SQLITE_BUSY], an
2b400 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 d [SQLITE_INTERR
2b410 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a UPT]) then the.*
2b420 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 * transaction mi
2b430 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 ght be rolled ba
2b440 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ck automatically
2b450 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 . The only way
2b460 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 to.** find out w
2b470 68 65 74 68 65 72 20 53 51 4c 69 74 65 20 61 75 hether SQLite au
2b480 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c tomatically roll
2b490 65 64 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e ed back the tran
2b4a0 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a saction after.**
2b4b0 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 an error is to
2b4c0 75 73 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f use this functio
2b4d0 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 n..**.** If anot
2b4e0 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 her thread chang
2b4f0 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 es the autocommi
2b500 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 t status of the
2b510 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
2b520 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 ection while thi
2b530 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e s routine is run
2b540 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 ning, then the r
2b550 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 eturn value.** i
2b560 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a s undefined..**.
2b570 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
2b580 20 5b 48 31 32 39 33 31 5d 20 5b 48 31 32 39 33 [H12931] [H1293
2b590 32 5d 20 5b 48 31 32 39 33 33 5d 20 5b 48 31 32 2] [H12933] [H12
2b5a0 39 33 34 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 934].*/.SQLITE_A
2b5b0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 PI int sqlite3_g
2b5c0 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 et_autocommit(sq
2b5d0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 lite3*);../*.**
2b5e0 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54 CAPI3REF: Find T
2b5f0 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 he Database Hand
2b600 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64 le Of A Prepared
2b610 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 31 Statement {H131
2b620 32 30 7d 20 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a 20} <S60600>.**.
2b630 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 ** The sqlite3_d
2b640 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 b_handle interfa
2b650 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b ce returns the [
2b660 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2b670 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 ion] handle.** t
2b680 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61 o which a [prepa
2b690 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 red statement] b
2b6a0 65 6c 6f 6e 67 73 2e 20 20 54 68 65 20 5b 64 61 elongs. The [da
2b6b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2b6c0 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 n].** returned b
2b6d0 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e y sqlite3_db_han
2b6e0 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 dle is the same
2b6f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2b700 74 69 6f 6e 5d 20 74 68 61 74 20 77 61 73 20 74 tion] that was t
2b710 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
2b720 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c t.** to the [sql
2b730 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
2b740 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 )] call (or its
2b750 76 61 72 69 61 6e 74 73 29 20 74 68 61 74 20 77 variants) that w
2b760 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 as used to.** cr
2b770 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 eate the stateme
2b780 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 nt in the first
2b790 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 place..**.** Req
2b7a0 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 33 31 uirements: [H131
2b7b0 32 33 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 23].*/.SQLITE_AP
2b7c0 49 20 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 I sqlite3 *sqlit
2b7d0 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c e3_db_handle(sql
2b7e0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a ite3_stmt*);../*
2b7f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 .** CAPI3REF: Fi
2b800 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72 65 70 nd the next prep
2b810 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 7b ared statement {
2b820 48 31 33 31 34 30 7d 20 3c 53 36 30 36 30 30 3e H13140} <S60600>
2b830 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 .**.** This inte
2b840 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
2b850 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e pointer to the n
2b860 65 78 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 ext [prepared st
2b870 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a atement] after.*
2b880 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61 74 * pStmt associat
2b890 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 ed with the [dat
2b8a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2b8b0 5d 20 70 44 62 2e 20 20 49 66 20 70 53 74 6d 74 ] pDb. If pStmt
2b8c0 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e is NULL.** then
2b8d0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 this interface
2b8e0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
2b8f0 72 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 70 r to the first p
2b900 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2b910 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 t.** associated
2b920 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61 73 with the databas
2b930 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 e connection pDb
2b940 2e 20 20 49 66 20 6e 6f 20 70 72 65 70 61 72 65 . If no prepare
2b950 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 d statement.** s
2b960 61 74 69 73 66 69 65 73 20 74 68 65 20 63 6f 6e atisfies the con
2b970 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 ditions of this
2b980 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 74 75 routine, it retu
2b990 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 rns NULL..**.**
2b9a0 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f The [database co
2b9b0 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 nnection] pointe
2b9c0 72 20 44 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f r D in a call to
2b9d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 .** [sqlite3_nex
2b9e0 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 t_stmt(D,S)] mus
2b9f0 74 20 72 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 t refer to an op
2ba00 65 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 en database.** c
2ba10 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e onnection and in
2ba20 20 70 61 72 74 69 63 75 6c 61 72 20 6d 75 73 74 particular must
2ba30 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 not be a NULL p
2ba40 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 52 65 ointer..**.** Re
2ba50 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 33 quirements: [H13
2ba60 31 34 33 5d 20 5b 48 31 33 31 34 36 5d 20 5b 48 143] [H13146] [H
2ba70 31 33 31 34 39 5d 20 5b 48 31 33 31 35 32 5d 0a 13149] [H13152].
2ba80 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 */.SQLITE_API sq
2ba90 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 lite3_stmt *sqli
2baa0 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 te3_next_stmt(sq
2bab0 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 lite3 *pDb, sqli
2bac0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
2bad0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2bae0 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f F: Commit And Ro
2baf0 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 llback Notificat
2bb00 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 ion Callbacks {H
2bb10 31 32 39 35 30 7d 20 3c 53 36 30 34 30 30 3e 0a 12950} <S60400>.
2bb20 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
2bb30 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 3_commit_hook()
2bb40 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 interface regist
2bb50 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a ers a callback.*
2bb60 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 * function to be
2bb70 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 invoked wheneve
2bb80 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 r a transaction
2bb90 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d is [COMMIT | com
2bba0 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 41 6e 79 20 mitted]..** Any
2bbb0 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 callback set by
2bbc0 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 a previous call
2bbd0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 to sqlite3_commi
2bbe0 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 t_hook().** for
2bbf0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
2bc00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
2bc10 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 overridden..** T
2bc20 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 he sqlite3_rollb
2bc30 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 ack_hook() inter
2bc40 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 face registers a
2bc50 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e callback.** fun
2bc60 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f ction to be invo
2bc70 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 ked whenever a t
2bc80 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 52 ransaction is [R
2bc90 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 OLLBACK | rolled
2bca0 20 62 61 63 6b 5d 2e 0a 2a 2a 20 41 6e 79 20 63 back]..** Any c
2bcb0 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 allback set by a
2bcc0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 previous call t
2bcd0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 o sqlite3_commit
2bce0 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 _hook().** for t
2bcf0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 he same database
2bd00 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f connection is o
2bd10 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 verridden..** Th
2bd20 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 e pArg argument
2bd30 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 is passed throug
2bd40 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 h to the callbac
2bd50 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c k..** If the cal
2bd60 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 lback on a commi
2bd70 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 t hook function
2bd80 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f returns non-zero
2bd90 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f ,.** then the co
2bda0 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65 mmit is converte
2bdb0 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 d into a rollbac
2bdc0 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 k..**.** If anot
2bdd0 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 her function was
2bde0 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 previously regi
2bdf0 73 74 65 72 65 64 2c 20 69 74 73 0a 2a 2a 20 70 stered, its.** p
2be00 41 72 67 20 76 61 6c 75 65 20 69 73 20 72 65 74 Arg value is ret
2be10 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 urned. Otherwis
2be20 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e e NULL is return
2be30 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 ed..**.** The ca
2be40 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 llback implement
2be50 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 ation must not d
2be60 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 o anything that
2be70 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 will modify.** t
2be80 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
2be90 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f ection that invo
2bea0 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b ked the callback
2beb0 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a . Any actions.*
2bec0 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 * to modify the
2bed0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2bee0 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 ion must be defe
2bef0 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 rred until after
2bf00 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 the.** completi
2bf10 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 on of the [sqlit
2bf20 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 e3_step()] call
2bf30 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 that triggered t
2bf40 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 he commit.** or
2bf50 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e rollback hook in
2bf60 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 the first place
2bf70 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b ..** Note that [
2bf80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
2bf90 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 v2()] and [sqlit
2bfa0 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 e3_step()] both
2bfb0 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 modify their.**
2bfc0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2bfd0 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 ions for the mea
2bfe0 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 ning of "modify"
2bff0 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 in this paragra
2c000 70 68 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 ph..**.** Regist
2c010 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e ering a NULL fun
2c020 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 ction disables t
2c030 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a he callback..**.
2c040 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d ** When the comm
2c050 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b it hook callback
2c060 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
2c070 20 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d zero, the [COMM
2c080 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e IT].** operation
2c090 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63 is allowed to c
2c0a0 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 ontinue normally
2c0b0 2e 20 20 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 . If the commit
2c0c0 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 hook.** returns
2c0d0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 non-zero, then
2c0e0 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 the [COMMIT] is
2c0f0 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 converted into a
2c100 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 [ROLLBACK]..**
2c110 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f The rollback hoo
2c120 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 k is invoked on
2c130 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20 a rollback that
2c140 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63 results from a c
2c150 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 ommit.** hook re
2c160 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f turning non-zero
2c170 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75 , just as it wou
2c180 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f ld be with any o
2c190 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a ther rollback..*
2c1a0 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 *.** For the pur
2c1b0 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 poses of this AP
2c1c0 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e I, a transaction
2c1d0 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 is said to have
2c1e0 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 been.** rolled
2c1f0 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 back if an expli
2c200 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 cit "ROLLBACK" s
2c210 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 tatement is exec
2c220 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 uted, or.** an e
2c230 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 rror or constrai
2c240 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 nt causes an imp
2c250 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 licit rollback t
2c260 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 54 68 65 20 o occur..** The
2c270 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 rollback callbac
2c280 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 k is not invoked
2c290 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f if a transactio
2c2a0 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 n is.** automati
2c2b0 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 cally rolled bac
2c2c0 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 64 61 k because the da
2c2d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2c2e0 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 n is closed..**
2c2f0 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c The rollback cal
2c300 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 lback is not inv
2c310 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 oked if a transa
2c320 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 72 6f 6c 6c ction is.** roll
2c330 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 ed back because
2c340 61 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63 a commit callbac
2c350 6b 20 72 65 74 75 72 6e 65 64 20 6e 6f 6e 2d 7a k returned non-z
2c360 65 72 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e 20 43 ero..** <todo> C
2c370 68 65 63 6b 20 6f 6e 20 74 68 69 73 20 3c 2f 74 heck on this </t
2c380 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 odo>.**.** See a
2c390 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 lso the [sqlite3
2c3a0 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 5d 20 _update_hook()]
2c3b0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a interface..**.**
2c3c0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
2c3d0 2a 20 5b 48 31 32 39 35 31 5d 20 5b 48 31 32 39 * [H12951] [H129
2c3e0 35 32 5d 20 5b 48 31 32 39 35 33 5d 20 5b 48 31 52] [H12953] [H1
2c3f0 32 39 35 34 5d 20 5b 48 31 32 39 35 35 5d 0a 2a 2954] [H12955].*
2c400 2a 20 5b 48 31 32 39 36 31 5d 20 5b 48 31 32 39 * [H12961] [H129
2c410 36 32 5d 20 5b 48 31 32 39 36 33 5d 20 5b 48 31 62] [H12963] [H1
2c420 32 39 36 34 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 2964].*/.SQLITE_
2c430 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 API void *sqlite
2c440 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 3_commit_hook(sq
2c450 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 lite3*, int(*)(v
2c460 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 oid*), void*);.S
2c470 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a QLITE_API void *
2c480 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b sqlite3_rollback
2c490 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 _hook(sqlite3*,
2c4a0 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c void(*)(void *),
2c4b0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 void*);../*.**
2c4c0 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20 43 CAPI3REF: Data C
2c4d0 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69 hange Notificati
2c4e0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 on Callbacks {H1
2c4f0 32 39 37 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2970} <S60400>.*
2c500 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
2c510 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69 _update_hook() i
2c520 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 nterface registe
2c530 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 rs a callback fu
2c540 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 nction.** with t
2c550 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
2c560 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66 nection] identif
2c570 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 ied by the first
2c580 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 argument.** to
2c590 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 be invoked whene
2c5a0 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 64 ver a row is upd
2c5b0 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f ated, inserted o
2c5c0 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e r deleted..** An
2c5d0 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 y callback set b
2c5e0 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c y a previous cal
2c5f0 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 l to this functi
2c600 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 on.** for the sa
2c610 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e me database conn
2c620 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 ection is overri
2c630 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 dden..**.** The
2c640 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
2c650 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
2c660 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 the function to
2c670 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a invoke when a.**
2c680 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c row is updated,
2c690 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c inserted or del
2c6a0 65 74 65 64 2e 0a 2a 2a 20 54 68 65 20 66 69 72 eted..** The fir
2c6b0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 st argument to t
2c6c0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 he callback is a
2c6d0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 copy of the thi
2c6e0 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 rd argument.** t
2c6f0 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 o sqlite3_update
2c700 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 54 68 65 20 _hook()..** The
2c710 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 second callback
2c720 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 argument is one
2c730 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 of [SQLITE_INSER
2c740 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 T], [SQLITE_DELE
2c750 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 TE],.** or [SQLI
2c760 54 45 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 65 TE_UPDATE], depe
2c770 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 nding on the ope
2c780 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 ration that caus
2c790 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a ed the callback.
2c7a0 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 ** to be invoked
2c7b0 2e 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 ..** The third a
2c7c0 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 nd fourth argume
2c7d0 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 nts to the callb
2c7e0 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e ack contain poin
2c7f0 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 ters to the.** d
2c800 61 74 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c atabase and tabl
2c810 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e e name containin
2c820 67 20 74 68 65 20 61 66 66 65 63 74 65 64 20 72 g the affected r
2c830 6f 77 2e 0a 2a 2a 20 54 68 65 20 66 69 6e 61 6c ow..** The final
2c840 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 callback parame
2c850 74 65 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 ter is the [rowi
2c860 64 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a d] of the row..*
2c870 2a 20 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 * In the case of
2c880 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 an update, this
2c890 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 is the [rowid]
2c8a0 61 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65 after the update
2c8b0 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a takes place..**
2c8c0 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20 68 .** The update h
2c8d0 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b ook is not invok
2c8e0 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c ed when internal
2c8f0 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61 system tables a
2c900 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 re.** modified (
2c910 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 i.e. sqlite_mast
2c920 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 er and sqlite_se
2c930 71 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 49 quence)..**.** I
2c940 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d n the current im
2c950 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68 plementation, th
2c960 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a e update hook.**
2c970 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 is not invoked
2c980 77 68 65 6e 20 64 75 70 6c 69 63 61 74 69 6f 6e when duplication
2c990 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 rows are delete
2c9a0 64 20 62 65 63 61 75 73 65 20 6f 66 20 61 6e 0a d because of an.
2c9b0 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 ** [ON CONFLICT
2c9c0 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52 45 | ON CONFLICT RE
2c9d0 50 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e 20 20 PLACE] clause.
2c9e0 4e 6f 72 20 69 73 20 74 68 65 20 75 70 64 61 74 Nor is the updat
2c9f0 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 e hook.** invoke
2ca00 64 20 77 68 65 6e 20 72 6f 77 73 20 61 72 65 20 d when rows are
2ca10 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20 74 68 deleted using th
2ca20 65 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 e [truncate opti
2ca30 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 mization]..** Th
2ca40 65 20 65 78 63 65 70 74 69 6f 6e 73 20 64 65 66 e exceptions def
2ca50 69 6e 65 64 20 69 6e 20 74 68 69 73 20 70 61 72 ined in this par
2ca60 61 67 72 61 70 68 20 6d 69 67 68 74 20 63 68 61 agraph might cha
2ca70 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a nge in a future.
2ca80 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 ** release of SQ
2ca90 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 Lite..**.** The
2caa0 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70 6c update hook impl
2cab0 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 ementation must
2cac0 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 not do anything
2cad0 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 that will modify
2cae0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 .** the database
2caf0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 connection that
2cb00 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 75 70 64 invoked the upd
2cb10 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 61 ate hook. Any a
2cb20 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 ctions.** to mod
2cb30 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 ify the database
2cb40 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 connection must
2cb50 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 be deferred unt
2cb60 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 il after the.**
2cb70 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 completion of th
2cb80 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 e [sqlite3_step(
2cb90 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 )] call that tri
2cba0 67 67 65 72 65 64 20 74 68 65 20 75 70 64 61 74 ggered the updat
2cbb0 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 e hook..** Note
2cbc0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 that [sqlite3_pr
2cbd0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 epare_v2()] and
2cbe0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
2cbf0 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 both modify the
2cc00 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 ir.** database c
2cc10 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 onnections for t
2cc20 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d he meaning of "m
2cc30 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 odify" in this p
2cc40 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 aragraph..**.**
2cc50 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 If another funct
2cc60 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73 ion was previous
2cc70 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69 ly registered, i
2cc80 74 73 20 70 41 72 67 20 76 61 6c 75 65 0a 2a 2a ts pArg value.**
2cc90 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f is returned. O
2cca0 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 therwise NULL is
2ccb0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
2ccc0 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 See also the [s
2ccd0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f qlite3_commit_ho
2cce0 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 ok()] and [sqlit
2ccf0 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b e3_rollback_hook
2cd00 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 ()].** interface
2cd10 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 s..**.** Require
2cd20 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 39 37 ments:.** [H1297
2cd30 31 5d 20 5b 48 31 32 39 37 33 5d 20 5b 48 31 32 1] [H12973] [H12
2cd40 39 37 35 5d 20 5b 48 31 32 39 37 37 5d 20 5b 48 975] [H12977] [H
2cd50 31 32 39 37 39 5d 20 5b 48 31 32 39 38 31 5d 20 12979] [H12981]
2cd60 5b 48 31 32 39 38 33 5d 20 5b 48 31 32 39 38 36 [H12983] [H12986
2cd70 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
2cd80 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 void *sqlite3_up
2cd90 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c date_hook(. sql
2cda0 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a ite3*, . void(*
2cdb0 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 )(void *,int ,ch
2cdc0 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 ar const *,char
2cdd0 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f const *,sqlite3_
2cde0 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a int64),. void*.
2cdf0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2ce00 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 EF: Enable Or Di
2ce10 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 61 67 sable Shared Pag
2ce20 65 72 20 43 61 63 68 65 20 7b 48 31 30 33 33 30 er Cache {H10330
2ce30 7d 20 3c 53 33 30 39 30 30 3e 0a 2a 2a 20 4b 45 } <S30900>.** KE
2ce40 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64 20 YWORDS: {shared
2ce50 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 cache}.**.** Thi
2ce60 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 s routine enable
2ce70 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 s or disables th
2ce80 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74 68 65 e sharing of the
2ce90 20 64 61 74 61 62 61 73 65 20 63 61 63 68 65 0a database cache.
2cea0 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20 64 61 ** and schema da
2ceb0 74 61 20 73 74 72 75 63 74 75 72 65 73 20 62 65 ta structures be
2cec0 74 77 65 65 6e 20 5b 64 61 74 61 62 61 73 65 20 tween [database
2ced0 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 63 6f 6e connection | con
2cee0 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 nections].** to
2cef0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
2cf00 65 2e 20 53 68 61 72 69 6e 67 20 69 73 20 65 6e e. Sharing is en
2cf10 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 abled if the arg
2cf20 75 6d 65 6e 74 20 69 73 20 74 72 75 65 0a 2a 2a ument is true.**
2cf30 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66 and disabled if
2cf40 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 the argument is
2cf50 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20 43 61 false..**.** Ca
2cf60 63 68 65 20 73 68 61 72 69 6e 67 20 69 73 20 65 che sharing is e
2cf70 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 73 61 62 nabled and disab
2cf80 6c 65 64 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 led for an entir
2cf90 65 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 20 54 68 e process..** Th
2cfa0 69 73 20 69 73 20 61 20 63 68 61 6e 67 65 20 61 is is a change a
2cfb0 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 s of SQLite vers
2cfc0 69 6f 6e 20 33 2e 35 2e 30 2e 20 49 6e 20 70 72 ion 3.5.0. In pr
2cfd0 69 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 ior versions of
2cfe0 53 51 4c 69 74 65 2c 0a 2a 2a 20 73 68 61 72 69 SQLite,.** shari
2cff0 6e 67 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f ng was enabled o
2d000 72 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 65 r disabled for e
2d010 61 63 68 20 74 68 72 65 61 64 20 73 65 70 61 72 ach thread separ
2d020 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ately..**.** The
2d030 20 63 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d cache sharing m
2d040 6f 64 65 20 73 65 74 20 62 79 20 74 68 69 73 20 ode set by this
2d050 69 6e 74 65 72 66 61 63 65 20 65 66 66 65 63 74 interface effect
2d060 73 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 s all subsequent
2d070 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 .** calls to [sq
2d080 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b lite3_open()], [
2d090 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
2d0a0 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 )], and [sqlite3
2d0b0 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 _open16()]..** E
2d0c0 78 69 73 74 69 6e 67 20 64 61 74 61 62 61 73 65 xisting database
2d0d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e connections con
2d0e0 74 69 6e 75 65 20 75 73 65 20 74 68 65 20 73 68 tinue use the sh
2d0f0 61 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 aring mode.** th
2d100 61 74 20 77 61 73 20 69 6e 20 65 66 66 65 63 74 at was in effect
2d110 20 61 74 20 74 68 65 20 74 69 6d 65 20 74 68 65 at the time the
2d120 79 20 77 65 72 65 20 6f 70 65 6e 65 64 2e 0a 2a y were opened..*
2d130 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 *.** Virtual tab
2d140 6c 65 73 20 63 61 6e 6e 6f 74 20 62 65 20 75 73 les cannot be us
2d150 65 64 20 77 69 74 68 20 61 20 73 68 61 72 65 64 ed with a shared
2d160 20 63 61 63 68 65 2e 20 20 57 68 65 6e 20 73 68 cache. When sh
2d170 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 ared.** cache is
2d180 20 65 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b 73 enabled, the [s
2d190 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f qlite3_create_mo
2d1a0 64 75 6c 65 28 29 5d 20 41 50 49 20 75 73 65 64 dule()] API used
2d1b0 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 to register.**
2d1c0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 77 virtual tables w
2d1d0 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 ill always retur
2d1e0 6e 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a n an error..**.*
2d1f0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 * This routine r
2d200 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f eturns [SQLITE_O
2d210 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63 K] if shared cac
2d220 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f he was enabled o
2d230 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 r disabled.** su
2d240 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 ccessfully. An
2d250 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 [error code] is
2d260 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69 returned otherwi
2d270 73 65 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65 64 se..**.** Shared
2d280 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62 6c cache is disabl
2d290 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20 42 ed by default. B
2d2a0 75 74 20 74 68 69 73 20 6d 69 67 68 74 20 63 68 ut this might ch
2d2b0 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72 ange in.** futur
2d2c0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 e releases of SQ
2d2d0 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61 74 69 Lite. Applicati
2d2e0 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20 61 62 ons that care ab
2d2f0 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 out shared.** ca
2d300 63 68 65 20 73 65 74 74 69 6e 67 20 73 68 6f 75 che setting shou
2d310 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c 69 63 ld set it explic
2d320 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 itly..**.** See
2d330 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74 65 20 53 Also: [SQLite S
2d340 68 61 72 65 64 2d 43 61 63 68 65 20 4d 6f 64 65 hared-Cache Mode
2d350 5d 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ].**.** Requirem
2d360 65 6e 74 73 3a 20 5b 48 31 30 33 33 31 5d 20 5b ents: [H10331] [
2d370 48 31 30 33 33 36 5d 20 5b 48 31 30 33 33 37 5d H10336] [H10337]
2d380 20 5b 48 31 30 33 33 39 5d 0a 2a 2f 0a 53 51 4c [H10339].*/.SQL
2d390 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
2d3a0 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 te3_enable_share
2d3b0 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f d_cache(int);../
2d3c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 *.** CAPI3REF: A
2d3d0 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48 ttempt To Free H
2d3e0 65 61 70 20 4d 65 6d 6f 72 79 20 7b 48 31 37 33 eap Memory {H173
2d3f0 34 30 7d 20 3c 53 33 30 32 32 30 3e 0a 2a 2a 0a 40} <S30220>.**.
2d400 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 ** The sqlite3_r
2d410 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 elease_memory()
2d420 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 interface attemp
2d430 74 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74 ts to free N byt
2d440 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 es.** of heap me
2d450 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 mory by dealloca
2d460 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 ting non-essenti
2d470 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 al memory alloca
2d480 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 tions.** held by
2d490 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 the database li
2d4a0 62 72 61 72 79 2e 20 7b 45 4e 44 7d 20 20 4d 65 brary. {END} Me
2d4b0 6d 6f 72 79 20 75 73 65 64 20 74 6f 20 63 61 63 mory used to cac
2d4c0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 70 he database.** p
2d4d0 61 67 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 ages to improve
2d4e0 70 65 72 66 6f 72 6d 61 6e 63 65 20 69 73 20 61 performance is a
2d4f0 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e n example of non
2d500 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 -essential memor
2d510 79 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 y..** sqlite3_re
2d520 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 lease_memory() r
2d530 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
2d540 72 20 6f 66 20 62 79 74 65 73 20 61 63 74 75 61 r of bytes actua
2d550 6c 6c 79 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 lly freed,.** wh
2d560 69 63 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 ich might be mor
2d570 65 20 6f 72 20 6c 65 73 73 20 74 68 61 6e 20 74 e or less than t
2d580 68 65 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 he amount reques
2d590 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 ted..**.** Requi
2d5a0 72 65 6d 65 6e 74 73 3a 20 5b 48 31 37 33 34 31 rements: [H17341
2d5b0 5d 20 5b 48 31 37 33 34 32 5d 0a 2a 2f 0a 53 51 ] [H17342].*/.SQ
2d5c0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
2d5d0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d ite3_release_mem
2d5e0 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a ory(int);../*.**
2d5f0 20 43 41 50 49 33 52 45 46 3a 20 49 6d 70 6f 73 CAPI3REF: Impos
2d600 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 e A Limit On Hea
2d610 70 20 53 69 7a 65 20 7b 48 31 37 33 35 30 7d 20 p Size {H17350}
2d620 3c 53 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S30220>.**.** T
2d630 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f he sqlite3_soft_
2d640 68 65 61 70 5f 6c 69 6d 69 74 28 29 20 69 6e 74 heap_limit() int
2d650 65 72 66 61 63 65 20 70 6c 61 63 65 73 20 61 20 erface places a
2d660 22 73 6f 66 74 22 20 6c 69 6d 69 74 0a 2a 2a 20 "soft" limit.**
2d670 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 on the amount of
2d680 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 heap memory tha
2d690 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 t may be allocat
2d6a0 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a ed by SQLite..**
2d6b0 20 49 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20 If an internal
2d6c0 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72 65 allocation is re
2d6d0 71 75 65 73 74 65 64 20 74 68 61 74 20 77 6f 75 quested that wou
2d6e0 6c 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a ld exceed the.**
2d6f0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 soft heap limit
2d700 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 , [sqlite3_relea
2d710 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20 se_memory()] is
2d720 69 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a invoked one or.*
2d730 2a 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 * more times to
2d740 66 72 65 65 20 75 70 20 73 6f 6d 65 20 73 70 61 free up some spa
2d750 63 65 20 62 65 66 6f 72 65 20 74 68 65 20 61 6c ce before the al
2d760 6c 6f 63 61 74 69 6f 6e 20 69 73 20 70 65 72 66 location is perf
2d770 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ormed..**.** The
2d780 20 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 limit is called
2d790 20 22 73 6f 66 74 22 2c 20 62 65 63 61 75 73 65 "soft", because
2d7a0 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c if [sqlite3_rel
2d7b0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a ease_memory()].*
2d7c0 2a 20 63 61 6e 6e 6f 74 20 66 72 65 65 20 73 75 * cannot free su
2d7d0 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 fficient memory
2d7e0 74 6f 20 70 72 65 76 65 6e 74 20 74 68 65 20 6c to prevent the l
2d7f0 69 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 20 imit from being
2d800 65 78 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65 exceeded,.** the
2d810 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 memory is alloc
2d820 61 74 65 64 20 61 6e 79 77 61 79 20 61 6e 64 20 ated anyway and
2d830 74 68 65 20 63 75 72 72 65 6e 74 20 6f 70 65 72 the current oper
2d840 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a ation proceeds..
2d850 2a 2a 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 **.** A negative
2d860 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 or zero value f
2d870 6f 72 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 or N means that
2d880 74 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 there is no soft
2d890 20 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a heap limit and.
2d8a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 ** [sqlite3_rele
2d8b0 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 ase_memory()] wi
2d8c0 6c 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 ll only be calle
2d8d0 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 d when memory is
2d8e0 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 54 exhausted..** T
2d8f0 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 he default value
2d900 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 for the soft he
2d910 61 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f ap limit is zero
2d920 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d ..**.** SQLite m
2d930 61 6b 65 73 20 61 20 62 65 73 74 20 65 66 66 6f akes a best effo
2d940 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 rt to honor the
2d950 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e soft heap limit.
2d960 0a 2a 2a 20 42 75 74 20 69 66 20 74 68 65 20 73 .** But if the s
2d970 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63 oft heap limit c
2d980 61 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64 annot be honored
2d990 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c , execution will
2d9a0 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 .** continue wit
2d9b0 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f hout error or no
2d9c0 74 69 66 69 63 61 74 69 6f 6e 2e 20 20 54 68 69 tification. Thi
2d9d0 73 20 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d s is why the lim
2d9e0 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20 it is.** called
2d9f0 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20 a "soft" limit.
2da00 20 49 74 20 69 73 20 61 64 76 69 73 6f 72 79 20 It is advisory
2da10 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f only..**.** Prio
2da20 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 r to SQLite vers
2da30 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20 ion 3.5.0, this
2da40 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e routine only con
2da50 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d strained the mem
2da60 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 ory.** allocated
2da70 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 by a single thr
2da80 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74 ead - the same t
2da90 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 74 hread in which t
2daa0 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 his routine.** r
2dab0 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20 uns. Beginning
2dac0 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73 with SQLite vers
2dad0 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73 ion 3.5.0, the s
2dae0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 oft heap limit i
2daf0 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20 s.** applied to
2db00 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 68 65 all threads. The
2db10 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 value specified
2db20 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 for the soft he
2db30 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61 ap limit.** is a
2db40 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e n upper bound on
2db50 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 the total memor
2db60 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 y allocation for
2db70 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 6e all threads. In
2db80 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e .** version 3.5.
2db90 30 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 0 there is no me
2dba0 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69 chanism for limi
2dbb0 74 69 6e 67 20 74 68 65 20 68 65 61 70 20 75 73 ting the heap us
2dbc0 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 age for.** indiv
2dbd0 69 64 75 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a idual threads..*
2dbe0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
2dbf0 73 3a 0a 2a 2a 20 5b 48 31 36 33 35 31 5d 20 5b s:.** [H16351] [
2dc00 48 31 36 33 35 32 5d 20 5b 48 31 36 33 35 33 5d H16352] [H16353]
2dc10 20 5b 48 31 36 33 35 34 5d 20 5b 48 31 36 33 35 [H16354] [H1635
2dc20 35 5d 20 5b 48 31 36 33 35 38 5d 0a 2a 2f 0a 53 5] [H16358].*/.S
2dc30 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
2dc40 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 qlite3_soft_heap
2dc50 5f 6c 69 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a _limit(int);../*
2dc60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 .** CAPI3REF: Ex
2dc70 74 72 61 63 74 20 4d 65 74 61 64 61 74 61 20 41 tract Metadata A
2dc80 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 bout A Column Of
2dc90 20 41 20 54 61 62 6c 65 20 7b 48 31 32 38 35 30 A Table {H12850
2dca0 7d 20 3c 53 36 30 33 30 30 3e 0a 2a 2a 0a 2a 2a } <S60300>.**.**
2dcb0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 This routine re
2dcc0 74 75 72 6e 73 20 6d 65 74 61 64 61 74 61 20 61 turns metadata a
2dcd0 62 6f 75 74 20 61 20 73 70 65 63 69 66 69 63 20 bout a specific
2dce0 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65 63 column of a spec
2dcf0 69 66 69 63 0a 2a 2a 20 64 61 74 61 62 61 73 65 ific.** database
2dd00 20 74 61 62 6c 65 20 61 63 63 65 73 73 69 62 6c table accessibl
2dd10 65 20 75 73 69 6e 67 20 74 68 65 20 5b 64 61 74 e using the [dat
2dd20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2dd30 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 70 61 73 73 ] handle.** pass
2dd40 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 ed as the first
2dd50 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e function argumen
2dd60 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6c t..**.** The col
2dd70 75 6d 6e 20 69 73 20 69 64 65 6e 74 69 66 69 65 umn is identifie
2dd80 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 2c d by the second,
2dd90 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 third and fourt
2dda0 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 0a h parameters to.
2ddb0 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e ** this function
2ddc0 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 . The second par
2ddd0 61 6d 65 74 65 72 20 69 73 20 65 69 74 68 65 72 ameter is either
2dde0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
2ddf0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e database.** (i.
2de00 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 e. "main", "temp
2de10 22 20 6f 72 20 61 6e 20 61 74 74 61 63 68 65 64 " or an attached
2de20 20 64 61 74 61 62 61 73 65 29 20 63 6f 6e 74 61 database) conta
2de30 69 6e 69 6e 67 20 74 68 65 20 73 70 65 63 69 66 ining the specif
2de40 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 ied.** table or
2de50 4e 55 4c 4c 2e 20 49 66 20 69 74 20 69 73 20 4e NULL. If it is N
2de60 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 ULL, then all at
2de70 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 tached databases
2de80 20 61 72 65 20 73 65 61 72 63 68 65 64 0a 2a 2a are searched.**
2de90 20 66 6f 72 20 74 68 65 20 74 61 62 6c 65 20 75 for the table u
2dea0 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c sing the same al
2deb0 67 6f 72 69 74 68 6d 20 75 73 65 64 20 62 79 20 gorithm used by
2dec0 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 the database eng
2ded0 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 ine to.** resolv
2dee0 65 20 75 6e 71 75 61 6c 69 66 69 65 64 20 74 61 e unqualified ta
2def0 62 6c 65 20 72 65 66 65 72 65 6e 63 65 73 2e 0a ble references..
2df00 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 **.** The third
2df10 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d and fourth param
2df20 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 eters to this fu
2df30 6e 63 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74 nction are the t
2df40 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a able and column.
2df50 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 ** name of the d
2df60 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 esired column, r
2df70 65 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 espectively. Nei
2df80 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 70 61 ther of these pa
2df90 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20 rameters.** may
2dfa0 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d be NULL..**.** M
2dfb0 65 74 61 64 61 74 61 20 69 73 20 72 65 74 75 72 etadata is retur
2dfc0 6e 65 64 20 62 79 20 77 72 69 74 69 6e 67 20 74 ned by writing t
2dfd0 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 o the memory loc
2dfe0 61 74 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73 ations passed as
2dff0 20 74 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20 the 5th.** and
2e000 73 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d subsequent param
2e010 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 eters to this fu
2e020 6e 63 74 69 6f 6e 2e 20 41 6e 79 20 6f 66 20 74 nction. Any of t
2e030 68 65 73 65 20 61 72 67 75 6d 65 6e 74 73 20 6d hese arguments m
2e040 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 ay be.** NULL, i
2e050 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 n which case the
2e060 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 corresponding e
2e070 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64 61 lement of metada
2e080 74 61 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a ta is omitted..*
2e090 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
2e0a0 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 >.** <table bord
2e0b0 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c er="1">.** <tr><
2e0c0 74 68 3e 20 50 61 72 61 6d 65 74 65 72 20 3c 74 th> Parameter <t
2e0d0 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e 54 79 70 h> Output<br>Typ
2e0e0 65 20 3c 74 68 3e 20 20 44 65 73 63 72 69 70 74 e <th> Descript
2e0f0 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 ion.**.** <tr><t
2e100 64 3e 20 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73 d> 5th <td> cons
2e110 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 44 61 74 t char* <td> Dat
2e120 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 a type.** <tr><t
2e130 64 3e 20 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73 d> 6th <td> cons
2e140 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d t char* <td> Nam
2e150 65 20 6f 66 20 64 65 66 61 75 6c 74 20 63 6f 6c e of default col
2e160 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a lation sequence.
2e170 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20 ** <tr><td> 7th
2e180 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 <td> int
2e190 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f <td> True if co
2e1a0 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e lumn has a NOT N
2e1b0 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a ULL constraint.*
2e1c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c * <tr><td> 8th <
2e1d0 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 td> int
2e1e0 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c <td> True if col
2e1f0 75 6d 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74 umn is part of t
2e200 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a he PRIMARY KEY.*
2e210 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c * <tr><td> 9th <
2e220 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 td> int
2e230 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c <td> True if col
2e240 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49 4e 43 52 umn is [AUTOINCR
2e250 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c EMENT].** </tabl
2e260 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f e>.** </blockquo
2e270 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 te>.**.** The me
2e280 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 mory pointed to
2e290 62 79 20 74 68 65 20 63 68 61 72 61 63 74 65 72 by the character
2e2a0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e pointers return
2e2b0 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64 65 ed for the.** de
2e2c0 63 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61 claration type a
2e2d0 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 nd collation seq
2e2e0 75 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f uence is valid o
2e2f0 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 nly until the ne
2e300 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e xt.** call to an
2e310 79 20 53 51 4c 69 74 65 20 41 50 49 20 66 75 6e y SQLite API fun
2e320 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 ction..**.** If
2e330 74 68 65 20 73 70 65 63 69 66 69 65 64 20 74 61 the specified ta
2e340 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79 20 ble is actually
2e350 61 20 76 69 65 77 2c 20 61 6e 20 5b 65 72 72 6f a view, an [erro
2e360 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 r code] is retur
2e370 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ned..**.** If th
2e380 65 20 73 70 65 63 69 66 69 65 64 20 63 6f 6c 75 e specified colu
2e390 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 2c 20 22 mn is "rowid", "
2e3a0 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f oid" or "_rowid_
2e3b0 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b 49 4e 54 " and an.** [INT
2e3c0 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 EGER PRIMARY KEY
2e3d0 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65 ] column has bee
2e3e0 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 n explicitly dec
2e3f0 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 68 65 20 lared, then the
2e400 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 output.** parame
2e410 74 65 72 73 20 61 72 65 20 73 65 74 20 66 6f 72 ters are set for
2e420 20 74 68 65 20 65 78 70 6c 69 63 69 74 6c 79 20 the explicitly
2e430 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e declared column.
2e440 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 0a If there is no.
2e450 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 ** explicitly de
2e460 63 6c 61 72 65 64 20 5b 49 4e 54 45 47 45 52 20 clared [INTEGER
2e470 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c PRIMARY KEY] col
2e480 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 umn, then the ou
2e490 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 tput.** paramete
2e4a0 72 73 20 61 72 65 20 73 65 74 20 61 73 20 66 6f rs are set as fo
2e4b0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 llows:.**.** <pr
2e4c0 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74 61 20 74 e>.** data t
2e4d0 79 70 65 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a ype: "INTEGER".*
2e4e0 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 * collation
2e4f0 73 65 71 75 65 6e 63 65 3a 20 22 42 49 4e 41 52 sequence: "BINAR
2e500 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75 Y".** not nu
2e510 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72 69 ll: 0.** pri
2e520 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 mary key: 1.**
2e530 20 20 20 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e auto incremen
2e540 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a t: 0.** </pre>.*
2e550 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 *.** This functi
2e560 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 on may load one
2e570 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 or more schemas
2e580 66 72 6f 6d 20 64 61 74 61 62 61 73 65 20 66 69 from database fi
2e590 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 les. If an.** er
2e5a0 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e ror occurs durin
2e5b0 67 20 74 68 69 73 20 70 72 6f 63 65 73 73 2c 20 g this process,
2e5c0 6f 72 20 69 66 20 74 68 65 20 72 65 71 75 65 73 or if the reques
2e5d0 74 65 64 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c ted table or col
2e5e0 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 umn.** cannot be
2e5f0 20 66 6f 75 6e 64 2c 20 61 6e 20 5b 65 72 72 6f found, an [erro
2e600 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 r code] is retur
2e610 6e 65 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 ned and an error
2e620 20 6d 65 73 73 61 67 65 20 6c 65 66 74 0a 2a 2a message left.**
2e630 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 in the [databas
2e640 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 e connection] (t
2e650 6f 20 62 65 20 72 65 74 72 69 65 76 65 64 20 75 o be retrieved u
2e660 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72 sing sqlite3_err
2e670 6d 73 67 28 29 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 msg())..**.** Th
2e680 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61 is API is only a
2e690 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 vailable if the
2e6a0 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 library was comp
2e6b0 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a iled with the.**
2e6c0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f [SQLITE_ENABLE_
2e6d0 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d COLUMN_METADATA]
2e6e0 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 C-preprocessor
2e6f0 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a symbol defined..
2e700 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
2e710 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f t sqlite3_table_
2e720 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28 column_metadata(
2e730 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
2e740 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
2e750 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e * Connection han
2e760 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 dle */. const c
2e770 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 har *zDbName,
2e780 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
2e790 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f name or NULL */
2e7a0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
2e7b0 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f TableName, /
2e7c0 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a * Table name */.
2e7d0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 const char *zC
2e7e0 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a olumnName, /*
2e7f0 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a Column name */.
2e800 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 char const **p
2e810 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f 2a zDataType, /*
2e820 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72 65 OUTPUT: Declare
2e830 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a 20 d data type */.
2e840 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a char const **pz
2e850 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20 CollSeq, /*
2e860 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f OUTPUT: Collatio
2e870 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20 n sequence name
2e880 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 */. int *pNotNu
2e890 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 ll,
2e8a0 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 /* OUTPUT: True
2e8b0 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e if NOT NULL con
2e8c0 73 74 72 61 69 6e 74 20 65 78 69 73 74 73 20 2a straint exists *
2e8d0 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61 72 /. int *pPrimar
2e8e0 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20 20 yKey,
2e8f0 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 /* OUTPUT: True
2e900 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f if column part o
2e910 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 f PK */. int *p
2e920 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20 20 Autoinc
2e930 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a /* OUTPUT:
2e940 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 True if column
2e950 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e is auto-incremen
2e960 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 t */.);../*.** C
2e970 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e API3REF: Load An
2e980 20 45 78 74 65 6e 73 69 6f 6e 20 7b 48 31 32 36 Extension {H126
2e990 30 30 7d 20 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 00} <S20500>.**.
2e9a0 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 ** This interfac
2e9b0 65 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69 74 e loads an SQLit
2e9c0 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 e extension libr
2e9d0 61 72 79 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d ary from the nam
2e9e0 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b ed file..**.** {
2e9f0 48 31 32 36 30 31 7d 20 54 68 65 20 73 71 6c 69 H12601} The sqli
2ea00 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 te3_load_extensi
2ea10 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 on() interface a
2ea20 74 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 ttempts to load
2ea30 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 an.** S
2ea40 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 QLite extension
2ea50 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 library containe
2ea60 64 20 69 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 d in the file zF
2ea70 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 ile..**.** {H126
2ea80 30 32 7d 20 54 68 65 20 65 6e 74 72 79 20 70 6f 02} The entry po
2ea90 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e 0a 2a 2a int is zProc..**
2eaa0 0a 2a 2a 20 7b 48 31 32 36 30 33 7d 20 7a 50 72 .** {H12603} zPr
2eab0 6f 63 20 6d 61 79 20 62 65 20 30 2c 20 69 6e 20 oc may be 0, in
2eac0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e which case the n
2ead0 61 6d 65 20 6f 66 20 74 68 65 20 65 6e 74 72 79 ame of the entry
2eae0 20 70 6f 69 6e 74 0a 2a 2a 20 20 20 20 20 20 20 point.**
2eaf0 20 20 20 64 65 66 61 75 6c 74 73 20 74 6f 20 22 defaults to "
2eb00 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 73 69 6f sqlite3_extensio
2eb10 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 0a 2a 2a 20 7b n_init"..**.** {
2eb20 48 31 32 36 30 34 7d 20 54 68 65 20 73 71 6c 69 H12604} The sqli
2eb30 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 te3_load_extensi
2eb40 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 on() interface s
2eb50 68 61 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 hall return.**
2eb60 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f [SQLITE_
2eb70 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 OK] on success a
2eb80 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 nd [SQLITE_ERROR
2eb90 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 ] if something g
2eba0 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 0a 2a 2a oes wrong..**.**
2ebb0 20 7b 48 31 32 36 30 35 7d 20 49 66 20 61 6e 20 {H12605} If an
2ebc0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 error occurs and
2ebd0 20 70 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 pzErrMsg is not
2ebe0 20 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 0, then the.**
2ebf0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
2ec00 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 3_load_extension
2ec10 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 ()] interface sh
2ec20 61 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a all attempt to.*
2ec30 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 6c 20 * fill
2ec40 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20 65 *pzErrMsg with e
2ec50 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 rror message tex
2ec60 74 20 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f t stored in memo
2ec70 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f ry.** o
2ec80 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
2ec90 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e lite3_malloc()].
2eca0 20 7b 45 4e 44 7d 20 20 54 68 65 20 63 61 6c 6c {END} The call
2ecb0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 ing function.**
2ecc0 20 20 20 20 20 20 20 20 20 73 68 6f 75 6c 64 20 should
2ecd0 66 72 65 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 free this memory
2ece0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c by calling [sql
2ecf0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a ite3_free()]..**
2ed00 0a 2a 2a 20 7b 48 31 32 36 30 36 7d 20 45 78 74 .** {H12606} Ext
2ed10 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d ension loading m
2ed20 75 73 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75 ust be enabled u
2ed30 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 sing.**
2ed40 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 [sqlite3_enable
2ed50 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 _load_extension(
2ed60 29 5d 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c )] prior to call
2ed70 69 6e 67 20 74 68 69 73 20 41 50 49 2c 0a 2a 2a ing this API,.**
2ed80 20 20 20 20 20 20 20 20 20 20 6f 74 68 65 72 77 otherw
2ed90 69 73 65 20 61 6e 20 65 72 72 6f 72 20 77 69 6c ise an error wil
2eda0 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a l be returned..*
2edb0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
2edc0 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 sqlite3_load_ex
2edd0 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74 tension(. sqlit
2ede0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
2edf0 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65 78 74 /* Load the ext
2ee00 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73 ension into this
2ee10 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
2ee20 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 tion */. const
2ee30 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20 char *zFile,
2ee40 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 73 /* Name of the s
2ee50 68 61 72 65 64 20 6c 69 62 72 61 72 79 20 63 6f hared library co
2ee60 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e 73 69 ntaining extensi
2ee70 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 on */. const ch
2ee80 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a ar *zProc, /*
2ee90 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20 44 Entry point. D
2eea0 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c erived from zFil
2eeb0 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68 61 72 e if 0 */. char
2eec0 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20 20 20 **pzErrMsg
2eed0 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72 20 6d /* Put error m
2eee0 65 73 73 61 67 65 20 68 65 72 65 20 69 66 20 6e essage here if n
2eef0 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a ot 0 */.);../*.*
2ef00 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 * CAPI3REF: Enab
2ef10 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 le Or Disable Ex
2ef20 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 tension Loading
2ef30 7b 48 31 32 36 32 30 7d 20 3c 53 32 30 35 30 30 {H12620} <S20500
2ef40 3e 0a 2a 2a 0a 2a 2a 20 53 6f 20 61 73 20 6e 6f >.**.** So as no
2ef50 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 t to open securi
2ef60 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 ty holes in olde
2ef70 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 r applications t
2ef80 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 hat are.** unpre
2ef90 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20 77 69 pared to deal wi
2efa0 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 th extension loa
2efb0 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 6d ding, and as a m
2efc0 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 6e eans of disablin
2efd0 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c g.** extension l
2efe0 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65 76 61 oading while eva
2eff0 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 luating user-ent
2f000 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20 66 6f ered SQL, the fo
2f010 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 69 llowing API.** i
2f020 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74 75 s provided to tu
2f030 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f rn the [sqlite3_
2f040 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 load_extension()
2f050 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 ] mechanism on a
2f060 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 45 78 nd off..**.** Ex
2f070 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 tension loading
2f080 69 73 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c is off by defaul
2f090 74 2e 20 53 65 65 20 74 69 63 6b 65 74 20 23 31 t. See ticket #1
2f0a0 38 36 33 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 863..**.** {H126
2f0b0 32 31 7d 20 43 61 6c 6c 20 74 68 65 20 73 71 6c 21} Call the sql
2f0c0 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 ite3_enable_load
2f0d0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75 _extension() rou
2f0e0 74 69 6e 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d tine with onoff=
2f0f0 3d 31 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 =1.** t
2f100 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e o turn extension
2f110 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 loading on and
2f120 63 61 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f call it with ono
2f130 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a ff==0 to turn.**
2f140 20 20 20 20 20 20 20 20 20 20 69 74 20 62 61 63 it bac
2f150 6b 20 6f 66 66 20 61 67 61 69 6e 2e 0a 2a 2a 0a k off again..**.
2f160 2a 2a 20 7b 48 31 32 36 32 32 7d 20 45 78 74 65 ** {H12622} Exte
2f170 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73 nsion loading is
2f180 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e off by default.
2f190 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
2f1a0 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c nt sqlite3_enabl
2f1b0 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e e_load_extension
2f1c0 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 69 6e (sqlite3 *db, in
2f1d0 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a t onoff);../*.**
2f1e0 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 6f 6d CAPI3REF: Autom
2f1f0 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64 20 41 6e atically Load An
2f200 20 45 78 74 65 6e 73 69 6f 6e 73 20 7b 48 31 32 Extensions {H12
2f210 36 34 30 7d 20 3c 53 32 30 35 30 30 3e 0a 2a 2a 640} <S20500>.**
2f220 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 63 61 6e .** This API can
2f230 20 62 65 20 69 6e 76 6f 6b 65 64 20 61 74 20 70 be invoked at p
2f240 72 6f 67 72 61 6d 20 73 74 61 72 74 75 70 20 69 rogram startup i
2f250 6e 20 6f 72 64 65 72 20 74 6f 20 72 65 67 69 73 n order to regis
2f260 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f ter.** one or mo
2f270 72 65 20 73 74 61 74 69 63 61 6c 6c 79 20 6c 69 re statically li
2f280 6e 6b 65 64 20 65 78 74 65 6e 73 69 6f 6e 73 20 nked extensions
2f290 74 68 61 74 20 77 69 6c 6c 20 62 65 20 61 76 61 that will be ava
2f2a0 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c ilable.** to all
2f2b0 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20 63 new [database c
2f2c0 6f 6e 6e 65 63 74 69 6f 6e 73 5d 2e 20 7b 45 4e onnections]. {EN
2f2d0 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f D}.**.** This ro
2f2e0 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61 20 70 utine stores a p
2f2f0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 65 78 ointer to the ex
2f300 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 61 72 tension in an ar
2f310 72 61 79 20 74 68 61 74 20 69 73 0a 2a 2a 20 6f ray that is.** o
2f320 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
2f330 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e lite3_malloc()].
2f340 20 20 49 66 20 79 6f 75 20 72 75 6e 20 61 20 6d If you run a m
2f350 65 6d 6f 72 79 20 6c 65 61 6b 20 63 68 65 63 6b emory leak check
2f360 65 72 0a 2a 2a 20 6f 6e 20 79 6f 75 72 20 70 72 er.** on your pr
2f370 6f 67 72 61 6d 20 61 6e 64 20 69 74 20 72 65 70 ogram and it rep
2f380 6f 72 74 73 20 61 20 6c 65 61 6b 20 62 65 63 61 orts a leak beca
2f390 75 73 65 20 6f 66 20 74 68 69 73 20 61 72 72 61 use of this arra
2f3a0 79 2c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 5b 73 71 y, invoke.** [sq
2f3b0 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f lite3_reset_auto
2f3c0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 _extension()] pr
2f3d0 69 6f 72 20 74 6f 20 73 68 75 74 64 6f 77 6e 20 ior to shutdown
2f3e0 74 6f 20 66 72 65 65 20 74 68 65 20 6d 65 6d 6f to free the memo
2f3f0 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34 ry..**.** {H1264
2f400 31 7d 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 1} This function
2f410 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 65 78 registers an ex
2f420 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f tension entry po
2f430 69 6e 74 20 74 68 61 74 20 69 73 0a 2a 2a 20 20 int that is.**
2f440 20 20 20 20 20 20 20 20 61 75 74 6f 6d 61 74 69 automati
2f450 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 20 77 68 cally invoked wh
2f460 65 6e 65 76 65 72 20 61 20 6e 65 77 20 5b 64 61 enever a new [da
2f470 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2f480 6e 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 n].** i
2f490 73 20 6f 70 65 6e 65 64 20 75 73 69 6e 67 20 5b s opened using [
2f4a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c sqlite3_open()],
2f4b0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
2f4c0 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 ()],.**
2f4d0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 or [sqlite3_ope
2f4e0 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b n_v2()]..**.** {
2f4f0 48 31 32 36 34 32 7d 20 44 75 70 6c 69 63 61 74 H12642} Duplicat
2f500 65 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 72 65 e extensions are
2f510 20 64 65 74 65 63 74 65 64 20 73 6f 20 63 61 6c detected so cal
2f520 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e ling this routin
2f530 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 75 e.** mu
2f540 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 ltiple times wit
2f550 68 20 74 68 65 20 73 61 6d 65 20 65 78 74 65 6e h the same exten
2f560 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73 73 sion is harmless
2f570 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34 33 7d ..**.** {H12643}
2f580 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 This routine st
2f590 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 ores a pointer t
2f5a0 6f 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 o the extension
2f5b0 69 6e 20 61 6e 20 61 72 72 61 79 0a 2a 2a 20 20 in an array.**
2f5c0 20 20 20 20 20 20 20 20 74 68 61 74 20 69 73 20 that is
2f5d0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 obtained from [s
2f5e0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
2f5f0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34 34 7d ..**.** {H12644}
2f600 20 41 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e Automatic exten
2f610 73 69 6f 6e 73 20 61 70 70 6c 79 20 61 63 72 6f sions apply acro
2f620 73 73 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a ss all threads..
2f630 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
2f640 74 20 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 t sqlite3_auto_e
2f650 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 20 28 2a xtension(void (*
2f660 78 45 6e 74 72 79 50 6f 69 6e 74 29 28 76 6f 69 xEntryPoint)(voi
2f670 64 29 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 d));../*.** CAPI
2f680 33 52 45 46 3a 20 52 65 73 65 74 20 41 75 74 6f 3REF: Reset Auto
2f690 6d 61 74 69 63 20 45 78 74 65 6e 73 69 6f 6e 20 matic Extension
2f6a0 4c 6f 61 64 69 6e 67 20 7b 48 31 32 36 36 30 7d Loading {H12660}
2f6b0 20 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S20500>.**.**
2f6c0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 This function di
2f6d0 73 61 62 6c 65 73 20 61 6c 6c 20 70 72 65 76 69 sables all previ
2f6e0 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 ously registered
2f6f0 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 65 78 automatic.** ex
2f700 74 65 6e 73 69 6f 6e 73 2e 20 7b 45 4e 44 7d 20 tensions. {END}
2f710 20 49 74 20 75 6e 64 6f 65 73 20 74 68 65 20 65 It undoes the e
2f720 66 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 72 69 ffect of all pri
2f730 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 or.** [sqlite3_a
2f740 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d uto_extension()]
2f750 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 calls..**.** {H
2f760 31 32 36 36 31 7d 20 54 68 69 73 20 66 75 6e 63 12661} This func
2f770 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 6c tion disables al
2f780 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 l previously reg
2f790 69 73 74 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 istered.**
2f7a0 20 20 20 20 61 75 74 6f 6d 61 74 69 63 20 65 78 automatic ex
2f7b0 74 65 6e 73 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 tensions..**.**
2f7c0 7b 48 31 32 36 36 32 7d 20 54 68 69 73 20 66 75 {H12662} This fu
2f7d0 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 nction disables
2f7e0 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 automatic extens
2f7f0 69 6f 6e 73 20 69 6e 20 61 6c 6c 20 74 68 72 65 ions in all thre
2f800 61 64 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ads..*/.SQLITE_A
2f810 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f PI void sqlite3_
2f820 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e reset_auto_exten
2f830 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a sion(void);../*.
2f840 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e ****** EXPERIMEN
2f850 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f TAL - subject to
2f860 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 change without
2f870 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a notice *********
2f880 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 *****.**.** The
2f890 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 interface to the
2f8a0 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d virtual-table m
2f8b0 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72 echanism is curr
2f8c0 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 ently considered
2f8d0 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 .** to be experi
2f8e0 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 mental. The int
2f8f0 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 erface might cha
2f900 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 nge in incompati
2f910 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 ble ways..** If
2f920 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 this is a proble
2f930 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f m for you, do no
2f940 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 t use the interf
2f950 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 ace at this time
2f960 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 ..**.** When the
2f970 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d virtual-table m
2f980 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 echanism stabili
2f990 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 zes, we will dec
2f9a0 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 lare the.** inte
2f9b0 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 rface fixed, sup
2f9c0 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 port it indefini
2f9d0 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 tely, and remove
2f9e0 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a this comment..*
2f9f0 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 /../*.** Structu
2fa00 72 65 73 20 75 73 65 64 20 62 79 20 74 68 65 20 res used by the
2fa10 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e virtual table in
2fa20 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 terface.*/.typed
2fa30 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
2fa40 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76 3_vtab sqlite3_v
2fa50 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72 tab;.typedef str
2fa60 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 uct sqlite3_inde
2fa70 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 x_info sqlite3_i
2fa80 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 ndex_info;.typed
2fa90 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
2faa0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71 3_vtab_cursor sq
2fab0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f lite3_vtab_curso
2fac0 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 r;.typedef struc
2fad0 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 t sqlite3_module
2fae0 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b sqlite3_module;
2faf0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2fb00 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 : Virtual Table
2fb10 4f 62 6a 65 63 74 20 7b 48 31 38 30 30 30 7d 20 Object {H18000}
2fb20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 <S20400>.** KEYW
2fb30 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f ORDS: sqlite3_mo
2fb40 64 75 6c 65 20 7b 76 69 72 74 75 61 6c 20 74 61 dule {virtual ta
2fb50 62 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 20 45 ble module}.** E
2fb60 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a XPERIMENTAL.**.*
2fb70 2a 20 54 68 69 73 20 73 74 72 75 63 74 75 72 65 * This structure
2fb80 2c 20 73 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c , sometimes call
2fb90 65 64 20 61 20 61 20 22 76 69 72 74 75 61 6c 20 ed a a "virtual
2fba0 74 61 62 6c 65 20 6d 6f 64 75 6c 65 22 2c 20 0a table module", .
2fbb0 2a 2a 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 ** defines the i
2fbc0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
2fbd0 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c a [virtual tabl
2fbe0 65 73 5d 2e 20 20 0a 2a 2a 20 54 68 69 73 20 73 es]. .** This s
2fbf0 74 72 75 63 74 75 72 65 20 63 6f 6e 73 69 73 74 tructure consist
2fc00 73 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 s mostly of meth
2fc10 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 ods for the modu
2fc20 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 le..**.** A virt
2fc30 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 ual table module
2fc40 20 69 73 20 63 72 65 61 74 65 64 20 62 79 20 66 is created by f
2fc50 69 6c 6c 69 6e 67 20 69 6e 20 61 20 70 65 72 73 illing in a pers
2fc60 69 73 74 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e istent.** instan
2fc70 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 ce of this struc
2fc80 74 75 72 65 20 61 6e 64 20 70 61 73 73 69 6e 67 ture and passing
2fc90 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
2fca0 61 74 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 at instance.** t
2fcb0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 o [sqlite3_creat
2fcc0 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b e_module()] or [
2fcd0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d sqlite3_create_m
2fce0 6f 64 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 odule_v2()]..**
2fcf0 54 68 65 20 72 65 67 69 73 74 72 61 74 69 6f 6e The registration
2fd00 20 72 65 6d 61 69 6e 73 20 76 61 6c 69 64 20 75 remains valid u
2fd10 6e 74 69 6c 20 69 74 20 69 73 20 72 65 70 6c 61 ntil it is repla
2fd20 63 65 64 20 62 79 20 61 20 64 69 66 66 65 72 65 ced by a differe
2fd30 6e 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 nt.** module or
2fd40 75 6e 74 69 6c 20 74 68 65 20 5b 64 61 74 61 62 until the [datab
2fd50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
2fd60 63 6c 6f 73 65 73 2e 20 20 54 68 65 20 63 6f 6e closes. The con
2fd70 74 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 73 20 tent.** of this
2fd80 73 74 72 75 63 74 75 72 65 20 6d 75 73 74 20 6e structure must n
2fd90 6f 74 20 63 68 61 6e 67 65 20 77 68 69 6c 65 20 ot change while
2fda0 69 74 20 69 73 20 72 65 67 69 73 74 65 72 65 64 it is registered
2fdb0 20 77 69 74 68 0a 2a 2a 20 61 6e 79 20 64 61 74 with.** any dat
2fdc0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2fdd0 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 ..*/.struct sqli
2fde0 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 te3_module {. i
2fdf0 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 nt iVersion;. i
2fe00 6e 74 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 nt (*xCreate)(sq
2fe10 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 lite3*, void *pA
2fe20 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 ux,.
2fe30 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e int argc, con
2fe40 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 st char *const*a
2fe50 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 rgv,.
2fe60 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 sqlite3_vtab
2fe70 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a **ppVTab, char*
2fe80 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e *);. int (*xCon
2fe90 6e 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 nect)(sqlite3*,
2fea0 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 void *pAux,.
2feb0 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 int a
2fec0 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 rgc, const char
2fed0 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 *const*argv,.
2fee0 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 sqli
2fef0 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 te3_vtab **ppVTa
2ff00 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e b, char**);. in
2ff10 74 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 t (*xBestIndex)(
2ff20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 sqlite3_vtab *pV
2ff30 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 Tab, sqlite3_ind
2ff40 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 ex_info*);. int
2ff50 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 (*xDisconnect)(
2ff60 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 sqlite3_vtab *pV
2ff70 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 Tab);. int (*xD
2ff80 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f estroy)(sqlite3_
2ff90 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 vtab *pVTab);.
2ffa0 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c int (*xOpen)(sql
2ffb0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 ite3_vtab *pVTab
2ffc0 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 , sqlite3_vtab_c
2ffd0 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 ursor **ppCursor
2ffe0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 );. int (*xClos
2fff0 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f e)(sqlite3_vtab_
30000 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 cursor*);. int
30010 28 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 (*xFilter)(sqlit
30020 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c e3_vtab_cursor*,
30030 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e int idxNum, con
30040 73 74 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c st char *idxStr,
30050 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 .
30060 20 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 int argc, sqlit
30070 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 e3_value **argv)
30080 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 ;. int (*xNext)
30090 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 (sqlite3_vtab_cu
300a0 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a rsor*);. int (*
300b0 78 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 xEof)(sqlite3_vt
300c0 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 ab_cursor*);. i
300d0 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 nt (*xColumn)(sq
300e0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f lite3_vtab_curso
300f0 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 r*, sqlite3_cont
30100 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e ext*, int);. in
30110 74 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 t (*xRowid)(sqli
30120 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a te3_vtab_cursor*
30130 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
30140 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 *pRowid);. int
30150 28 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69 74 (*xUpdate)(sqlit
30160 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 e3_vtab *, int,
30170 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a sqlite3_value **
30180 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
30190 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 *);. int (*xBeg
301a0 69 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 in)(sqlite3_vtab
301b0 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 *pVTab);. int
301c0 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 (*xSync)(sqlite3
301d0 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 _vtab *pVTab);.
301e0 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 int (*xCommit)(
301f0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 sqlite3_vtab *pV
30200 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 Tab);. int (*xR
30210 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 ollback)(sqlite3
30220 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 _vtab *pVTab);.
30230 20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 int (*xFindFunc
30240 74 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 tion)(sqlite3_vt
30250 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e ab *pVtab, int n
30260 41 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 Arg, const char
30270 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 *zName,.
30280 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 v
30290 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 oid (**pxFunc)(s
302a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
302b0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 int,sqlite3_valu
302c0 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20 e**),.
302d0 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 voi
302e0 64 20 2a 2a 70 70 41 72 67 29 3b 0a 20 20 69 6e d **ppArg);. in
302f0 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c t (*xRename)(sql
30300 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 ite3_vtab *pVtab
30310 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
30320 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ew);.};../*.** C
30330 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c API3REF: Virtual
30340 20 54 61 62 6c 65 20 49 6e 64 65 78 69 6e 67 20 Table Indexing
30350 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 7b 48 31 38 Information {H18
30360 31 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 100} <S20400>.**
30370 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 KEYWORDS: sqlit
30380 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a e3_index_info.**
30390 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a EXPERIMENTAL.**
303a0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
303b0 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 index_info struc
303c0 74 75 72 65 20 61 6e 64 20 69 74 73 20 73 75 62 ture and its sub
303d0 73 74 72 75 63 74 75 72 65 73 20 69 73 20 75 73 structures is us
303e0 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e ed to.** pass in
303f0 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 formation into a
30400 6e 64 20 72 65 63 65 69 76 65 20 74 68 65 20 72 nd receive the r
30410 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 eply from the [x
30420 42 65 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 BestIndex].** me
30430 74 68 6f 64 20 6f 66 20 61 20 5b 76 69 72 74 75 thod of a [virtu
30440 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d al table module]
30450 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e . The fields un
30460 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 der **Inputs** a
30470 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 re the.** inputs
30480 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61 to xBestIndex a
30490 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 nd are read-only
304a0 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e . xBestIndex in
304b0 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 serts its.** res
304c0 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a ults into the **
304d0 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 Outputs** fields
304e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43 6f 6e ..**.** The aCon
304f0 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 straint[] array
30500 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c records WHERE cl
30510 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 ause constraints
30520 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a of the form:.**
30530 0a 2a 2a 20 3c 70 72 65 3e 63 6f 6c 75 6d 6e 20 .** <pre>column
30540 4f 50 20 65 78 70 72 3c 2f 70 72 65 3e 0a 2a 2a OP expr</pre>.**
30550 0a 2a 2a 20 77 68 65 72 65 20 4f 50 20 69 73 20 .** where OP is
30560 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 =, <, <=,
30570 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 20 >, or >=.
30580 20 54 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 The particular
30590 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a 20 73 operator is.** s
305a0 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73 74 72 tored in aConstr
305b0 61 69 6e 74 5b 5d 2e 6f 70 2e 20 20 54 68 65 20 aint[].op. The
305c0 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c index of the col
305d0 75 6d 6e 20 69 73 20 73 74 6f 72 65 64 20 69 6e umn is stored in
305e0 0a 2a 2a 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b .** aConstraint[
305f0 5d 2e 69 43 6f 6c 75 6d 6e 2e 20 20 61 43 6f 6e ].iColumn. aCon
30600 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 straint[].usable
30610 20 69 73 20 54 52 55 45 20 69 66 20 74 68 65 0a is TRUE if the.
30620 2a 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72 ** expr on the r
30630 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63 ight-hand side c
30640 61 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 an be evaluated
30650 28 61 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f (and thus the co
30660 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 nstraint.** is u
30670 73 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 sable) and false
30680 20 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 0a 2a if it cannot..*
30690 2a 0a 2a 2a 20 54 68 65 20 6f 70 74 69 6d 69 7a *.** The optimiz
306a0 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 er automatically
306b0 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73 20 6f inverts terms o
306c0 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78 70 72 f the form "expr
306d0 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 OP column".** a
306e0 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 20 73 nd makes other s
306f0 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 20 74 implifications t
30700 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 o the WHERE clau
30710 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 se in an attempt
30720 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61 to.** get as ma
30730 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 ny WHERE clause
30740 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 20 66 terms into the f
30750 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 orm shown above
30760 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 as possible..**
30770 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b The aConstraint[
30780 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20 72 65 70 ] array only rep
30790 6f 72 74 73 20 57 48 45 52 45 20 63 6c 61 75 73 orts WHERE claus
307a0 65 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20 63 e terms in the c
307b0 6f 72 72 65 63 74 0a 2a 2a 20 66 6f 72 6d 20 74 orrect.** form t
307c0 68 61 74 20 72 65 66 65 72 20 74 6f 20 74 68 65 hat refer to the
307d0 20 70 61 72 74 69 63 75 6c 61 72 20 76 69 72 74 particular virt
307e0 75 61 6c 20 74 61 62 6c 65 20 62 65 69 6e 67 20 ual table being
307f0 71 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 queried..**.** I
30800 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 nformation about
30810 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c the ORDER BY cl
30820 61 75 73 65 20 69 73 20 73 74 6f 72 65 64 20 69 ause is stored i
30830 6e 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a n aOrderBy[]..**
30840 20 45 61 63 68 20 74 65 72 6d 20 6f 66 20 61 4f Each term of aO
30850 72 64 65 72 42 79 20 72 65 63 6f 72 64 73 20 61 rderBy records a
30860 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f column of the O
30870 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 2e 0a RDER BY clause..
30880 2a 2a 0a 2a 2a 20 54 68 65 20 5b 78 42 65 73 74 **.** The [xBest
30890 49 6e 64 65 78 5d 20 6d 65 74 68 6f 64 20 6d 75 Index] method mu
308a0 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61 st fill aConstra
308b0 69 6e 74 55 73 61 67 65 5b 5d 20 77 69 74 68 20 intUsage[] with
308c0 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 information.** a
308d0 62 6f 75 74 20 77 68 61 74 20 70 61 72 61 6d 65 bout what parame
308e0 74 65 72 73 20 74 6f 20 70 61 73 73 20 74 6f 20 ters to pass to
308f0 78 46 69 6c 74 65 72 2e 20 20 49 66 20 61 72 67 xFilter. If arg
30900 76 49 6e 64 65 78 3e 30 20 74 68 65 6e 0a 2a 2a vIndex>0 then.**
30910 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 the right-hand
30920 73 69 64 65 20 6f 66 20 74 68 65 20 63 6f 72 72 side of the corr
30930 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f 6e 73 74 esponding aConst
30940 72 61 69 6e 74 5b 5d 20 69 73 20 65 76 61 6c 75 raint[] is evalu
30950 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62 65 63 6f ated.** and beco
30960 6d 65 73 20 74 68 65 20 61 72 67 76 49 6e 64 65 mes the argvInde
30970 78 2d 74 68 20 65 6e 74 72 79 20 69 6e 20 61 72 x-th entry in ar
30980 67 76 2e 20 20 49 66 20 61 43 6f 6e 73 74 72 61 gv. If aConstra
30990 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a intUsage[].omit.
309a0 2a 2a 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e ** is true, then
309b0 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 the constraint
309c0 69 73 20 61 73 73 75 6d 65 64 20 74 6f 20 62 65 is assumed to be
309d0 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62 fully handled b
309e0 79 20 74 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c y the.** virtual
309f0 20 74 61 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f table and is no
30a00 74 20 63 68 65 63 6b 65 64 20 61 67 61 69 6e 20 t checked again
30a10 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a by SQLite..**.**
30a20 20 54 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 The idxNum and
30a30 69 64 78 50 74 72 20 76 61 6c 75 65 73 20 61 72 idxPtr values ar
30a40 65 20 72 65 63 6f 72 64 65 64 20 61 6e 64 20 70 e recorded and p
30a50 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a assed into the.*
30a60 2a 20 5b 78 46 69 6c 74 65 72 5d 20 6d 65 74 68 * [xFilter] meth
30a70 6f 64 2e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f od..** [sqlite3_
30a80 66 72 65 65 28 29 5d 20 69 73 20 75 73 65 64 20 free()] is used
30a90 74 6f 20 66 72 65 65 20 69 64 78 50 74 72 20 69 to free idxPtr i
30aa0 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 66 0a 2a f and only iff.*
30ab0 2a 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50 * needToFreeIdxP
30ac0 74 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a tr is true..**.*
30ad0 2a 20 54 68 65 20 6f 72 64 65 72 42 79 43 6f 6e * The orderByCon
30ae0 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 74 sumed means that
30af0 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 5b 78 46 output from [xF
30b00 69 6c 74 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 ilter]/[xNext] w
30b10 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 ill occur in.**
30b20 74 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65 the correct orde
30b30 72 20 74 6f 20 73 61 74 69 73 66 79 20 74 68 65 r to satisfy the
30b40 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 ORDER BY clause
30b50 20 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61 so that no sepa
30b60 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 rate.** sorting
30b70 73 74 65 70 20 69 73 20 72 65 71 75 69 72 65 64 step is required
30b80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 73 74 69 ..**.** The esti
30b90 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20 matedCost value
30ba0 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f is an estimate o
30bb0 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f f the cost of do
30bc0 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 ing the.** parti
30bd0 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 cular lookup. A
30be0 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 full scan of a
30bf0 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 table with N ent
30c00 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 ries should have
30c10 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e .** a cost of N.
30c20 20 20 41 20 62 69 6e 61 72 79 20 73 65 61 72 63 A binary searc
30c30 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20 h of a table of
30c40 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 N entries should
30c50 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 have a.** cost
30c60 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 of approximately
30c70 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 log(N)..*/.stru
30c80 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 ct sqlite3_index
30c90 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 _info {. /* Inp
30ca0 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f uts */. int nCo
30cb0 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 nstraint;
30cc0 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 /* Number of
30cd0 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e entries in aCon
30ce0 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 straint */. str
30cf0 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 uct sqlite3_inde
30d00 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 x_constraint {.
30d10 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b int iColumn;
30d20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
30d30 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d Column on left-
30d40 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e hand side of con
30d50 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 straint */.
30d60 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 unsigned char op
30d70 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e ; /* Con
30d80 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 straint operator
30d90 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 */. unsigne
30da0 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 d char usable;
30db0 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 /* True if th
30dc0 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 is constraint is
30dd0 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 usable */.
30de0 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b int iTermOffset;
30df0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 /* Use
30e00 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 d internally - x
30e10 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 BestIndex should
30e20 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a ignore */. } *
30e30 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 aConstraint;
30e40 20 20 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 /* Table
30e50 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 of WHERE clause
30e60 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a constraints */.
30e70 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 int nOrderBy;
30e80 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
30e90 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 Number of terms
30ea0 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 in the ORDER BY
30eb0 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 clause */. stru
30ec0 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 ct sqlite3_index
30ed0 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20 _orderby {.
30ee0 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 int iColumn;
30ef0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c /* Col
30f00 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 umn number */.
30f10 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 unsigned char
30f20 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 desc; /*
30f30 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20 True for DESC.
30f40 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a False for ASC. *
30f50 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b /. } *aOrderBy;
30f60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
30f70 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59 20 63 * The ORDER BY c
30f80 6c 61 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 lause */. /* Ou
30f90 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 tputs */. struc
30fa0 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f t sqlite3_index_
30fb0 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65 constraint_usage
30fc0 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49 {. int argvI
30fd0 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20 20 20 ndex;
30fe0 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 /* if >0, constr
30ff0 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20 aint is part of
31000 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20 argv to xFilter
31010 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20 */. unsigned
31020 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 char omit;
31030 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 /* Do not code a
31040 20 74 65 73 74 20 66 6f 72 20 74 68 69 73 20 63 test for this c
31050 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d onstraint */. }
31060 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 *aConstraintUsa
31070 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d ge;. int idxNum
31080 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ;
31090 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20 /* Number used
310a0 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 to identify the
310b0 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 index */. char
310c0 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20 20 20 *idxStr;
310d0 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c /* String,
310e0 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e possibly obtain
310f0 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ed from sqlite3_
31100 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 malloc */. int
31110 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53 74 72 needToFreeIdxStr
31120 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69 ; /* Free i
31130 64 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69 dxStr using sqli
31140 74 65 33 5f 66 72 65 65 28 29 20 69 66 20 74 72 te3_free() if tr
31150 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 ue */. int orde
31160 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 rByConsumed;
31170 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 /* True if ou
31180 74 70 75 74 20 69 73 20 61 6c 72 65 61 64 79 20 tput is already
31190 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 ordered */. dou
311a0 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 ble estimatedCos
311b0 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d t; /* Estim
311c0 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69 ated cost of usi
311d0 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f ng this index */
311e0 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .};.#define SQLI
311f0 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 TE_INDEX_CONSTRA
31200 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 65 66 INT_EQ 2.#def
31210 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 ine SQLITE_INDEX
31220 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 _CONSTRAINT_GT
31230 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 4.#define SQLI
31240 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 TE_INDEX_CONSTRA
31250 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 INT_LE 8.#def
31260 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 ine SQLITE_INDEX
31270 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 _CONSTRAINT_LT
31280 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 16.#define SQL
31290 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 ITE_INDEX_CONSTR
312a0 41 49 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 64 AINT_GE 32.#d
312b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 efine SQLITE_IND
312c0 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 EX_CONSTRAINT_MA
312d0 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 TCH 64../*.** CA
312e0 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 PI3REF: Register
312f0 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 A Virtual Table
31300 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 Implementation
31310 7b 48 31 38 32 30 30 7d 20 3c 53 32 30 34 30 30 {H18200} <S20400
31320 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 >.** EXPERIMENTA
31330 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 L.**.** This rou
31340 74 69 6e 65 20 69 73 20 75 73 65 64 20 74 6f 20 tine is used to
31350 72 65 67 69 73 74 65 72 20 61 20 6e 65 77 20 5b register a new [
31360 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f virtual table mo
31370 64 75 6c 65 5d 20 6e 61 6d 65 2e 0a 2a 2a 20 4d dule] name..** M
31380 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75 73 74 odule names must
31390 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 62 be registered b
313a0 65 66 6f 72 65 0a 2a 2a 20 63 72 65 61 74 69 6e efore.** creatin
313b0 67 20 61 20 6e 65 77 20 5b 76 69 72 74 75 61 6c g a new [virtual
313c0 20 74 61 62 6c 65 5d 20 75 73 69 6e 67 20 74 68 table] using th
313d0 65 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 62 65 66 e module, or bef
313e0 6f 72 65 20 75 73 69 6e 67 20 61 0a 2a 2a 20 70 ore using a.** p
313f0 72 65 65 78 69 73 74 69 6e 67 20 5b 76 69 72 74 reexisting [virt
31400 75 61 6c 20 74 61 62 6c 65 5d 20 66 6f 72 20 74 ual table] for t
31410 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a he module..**.**
31420 20 54 68 65 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 The module name
31430 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 6f is registered o
31440 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 n the [database
31450 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 connection] spec
31460 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 ified.** by the
31470 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e first parameter.
31480 20 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 The name of th
31490 65 20 6d 6f 64 75 6c 65 20 69 73 20 67 69 76 65 e module is give
314a0 6e 20 62 79 20 74 68 65 20 0a 2a 2a 20 73 65 63 n by the .** sec
314b0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 ond parameter.
314c0 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 The third parame
314d0 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ter is a pointer
314e0 20 74 6f 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 to.** the imple
314f0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 mentation of the
31500 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 [virtual table
31510 6d 6f 64 75 6c 65 5d 2e 20 20 20 54 68 65 20 66 module]. The f
31520 6f 75 72 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 ourth.** paramet
31530 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 er is an arbitra
31540 72 79 20 63 6c 69 65 6e 74 20 64 61 74 61 20 70 ry client data p
31550 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 ointer that is p
31560 61 73 73 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a assed through.**
31570 20 69 6e 74 6f 20 74 68 65 20 5b 78 43 72 65 61 into the [xCrea
31580 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 te] and [xConnec
31590 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 74 68 t] methods of th
315a0 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 e virtual table
315b0 6d 6f 64 75 6c 65 0a 2a 2a 20 77 68 65 6e 20 61 module.** when a
315c0 20 6e 65 77 20 76 69 72 74 75 61 6c 20 74 61 62 new virtual tab
315d0 6c 65 20 69 73 20 62 65 20 62 65 69 6e 67 20 63 le is be being c
315e0 72 65 61 74 65 64 20 6f 72 20 72 65 69 6e 69 74 reated or reinit
315f0 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 ialized..**.** T
31600 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 68 61 his interface ha
31610 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 s exactly the sa
31620 6d 65 20 65 66 66 65 63 74 20 61 73 20 63 61 6c me effect as cal
31630 6c 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ling.** [sqlite3
31640 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 _create_module_v
31650 32 28 29 5d 20 77 69 74 68 20 61 20 4e 55 4c 4c 2()] with a NULL
31660 20 63 6c 69 65 6e 74 20 64 61 74 61 20 64 65 73 client data des
31670 74 72 75 63 74 6f 72 2e 0a 2a 2f 0a 53 51 4c 49 tructor..*/.SQLI
31680 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 TE_API SQLITE_EX
31690 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 PERIMENTAL int s
316a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f qlite3_create_mo
316b0 64 75 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 dule(. sqlite3
316c0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
316d0 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e /* SQLite con
316e0 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 nection to regis
316f0 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 ter module with
31700 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
31710 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 *zName,
31720 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d /* Name of the m
31730 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 odule */. const
31740 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 sqlite3_module
31750 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 *p, /* Methods
31760 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 for the module
31770 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 43 6c 69 65 */. void *pClie
31780 6e 74 44 61 74 61 20 20 20 20 20 20 20 20 20 20 ntData
31790 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 /* Client data f
317a0 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e or xCreate/xConn
317b0 65 63 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a ect */.);../*.**
317c0 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 CAPI3REF: Regis
317d0 74 65 72 20 41 20 56 69 72 74 75 61 6c 20 54 61 ter A Virtual Ta
317e0 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 ble Implementati
317f0 6f 6e 20 7b 48 31 38 32 31 30 7d 20 3c 53 32 30 on {H18210} <S20
31800 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 400>.** EXPERIME
31810 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 NTAL.**.** This
31820 72 6f 75 74 69 6e 65 20 69 73 20 69 64 65 6e 74 routine is ident
31830 69 63 61 6c 20 74 6f 20 74 68 65 20 5b 73 71 6c ical to the [sql
31840 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 ite3_create_modu
31850 6c 65 28 29 5d 20 6d 65 74 68 6f 64 2c 0a 2a 2a le()] method,.**
31860 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 except that it
31870 68 61 73 20 61 6e 20 65 78 74 72 61 20 70 61 72 has an extra par
31880 61 6d 65 74 65 72 20 74 6f 20 73 70 65 63 69 66 ameter to specif
31890 79 20 0a 2a 2a 20 61 20 64 65 73 74 72 75 63 74 y .** a destruct
318a0 6f 72 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 or function for
318b0 74 68 65 20 63 6c 69 65 6e 74 20 64 61 74 61 20 the client data
318c0 70 6f 69 6e 74 65 72 2e 20 20 53 51 4c 69 74 65 pointer. SQLite
318d0 20 77 69 6c 6c 0a 2a 2a 20 69 6e 76 6f 6b 65 20 will.** invoke
318e0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 the destructor f
318f0 75 6e 63 74 69 6f 6e 20 28 69 66 20 69 74 20 69 unction (if it i
31900 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 77 68 65 6e s not NULL) when
31910 20 53 51 4c 69 74 65 0a 2a 2a 20 6e 6f 20 6c 6f SQLite.** no lo
31920 6e 67 65 72 20 6e 65 65 64 73 20 74 68 65 20 70 nger needs the p
31930 43 6c 69 65 6e 74 44 61 74 61 20 70 6f 69 6e 74 ClientData point
31940 65 72 2e 20 20 0a 2a 2f 0a 53 51 4c 49 54 45 5f er. .*/.SQLITE_
31950 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 API SQLITE_EXPER
31960 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 IMENTAL int sqli
31970 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c te3_create_modul
31980 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 e_v2(. sqlite3
31990 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
319a0 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e /* SQLite con
319b0 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 nection to regis
319c0 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 ter module with
319d0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
319e0 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 *zName,
319f0 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d /* Name of the m
31a00 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 odule */. const
31a10 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 sqlite3_module
31a20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 *p, /* Methods
31a30 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 for the module
31a40 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 43 6c 69 65 */. void *pClie
31a50 6e 74 44 61 74 61 2c 20 20 20 20 20 20 20 20 20 ntData,
31a60 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 /* Client data f
31a70 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e or xCreate/xConn
31a80 65 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 ect */. void(*x
31a90 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 20 Destroy)(void*)
31aa0 20 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 /* Module de
31ab0 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f structor functio
31ac0 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 n */.);../*.** C
31ad0 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c API3REF: Virtual
31ae0 20 54 61 62 6c 65 20 49 6e 73 74 61 6e 63 65 20 Table Instance
31af0 4f 62 6a 65 63 74 20 7b 48 31 38 30 31 30 7d 20 Object {H18010}
31b00 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 <S20400>.** KEYW
31b10 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 ORDS: sqlite3_vt
31b20 61 62 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 ab.** EXPERIMENT
31b30 41 4c 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b AL.**.** Every [
31b40 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f virtual table mo
31b50 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 dule] implementa
31b60 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 tion uses a subc
31b70 6c 61 73 73 0a 2a 2a 20 6f 66 20 74 68 65 20 66 lass.** of the f
31b80 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 ollowing structu
31b90 72 65 20 74 6f 20 64 65 73 63 72 69 62 65 20 61 re to describe a
31ba0 20 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 particular inst
31bb0 61 6e 63 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b ance.** of the [
31bc0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 20 virtual table].
31bd0 20 45 61 63 68 20 73 75 62 63 6c 61 73 73 20 77 Each subclass w
31be0 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 69 6c 6f 72 ill.** be tailor
31bf0 65 64 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 ed to the specif
31c00 69 63 20 6e 65 65 64 73 20 6f 66 20 74 68 65 20 ic needs of the
31c10 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 module implement
31c20 61 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 70 75 ation..** The pu
31c30 72 70 6f 73 65 20 6f 66 20 74 68 69 73 20 73 75 rpose of this su
31c40 70 65 72 63 6c 61 73 73 20 69 73 20 74 6f 20 64 perclass is to d
31c50 65 66 69 6e 65 20 63 65 72 74 61 69 6e 20 66 69 efine certain fi
31c60 65 6c 64 73 20 74 68 61 74 20 61 72 65 0a 2a 2a elds that are.**
31c70 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 6d common to all m
31c80 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 odule implementa
31c90 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 tions..**.** Vir
31ca0 74 75 61 6c 20 74 61 62 6c 65 73 20 6d 65 74 68 tual tables meth
31cb0 6f 64 73 20 63 61 6e 20 73 65 74 20 61 6e 20 65 ods can set an e
31cc0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 62 79 20 rror message by
31cd0 61 73 73 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 assigning a.** s
31ce0 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 tring obtained f
31cf0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 rom [sqlite3_mpr
31d00 69 6e 74 66 28 29 5d 20 74 6f 20 7a 45 72 72 4d intf()] to zErrM
31d10 73 67 2e 20 20 54 68 65 20 6d 65 74 68 6f 64 20 sg. The method
31d20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 should.** take c
31d30 61 72 65 20 74 68 61 74 20 61 6e 79 20 70 72 69 are that any pri
31d40 6f 72 20 73 74 72 69 6e 67 20 69 73 20 66 72 65 or string is fre
31d50 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 ed by a call to
31d60 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
31d70 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 73 73 .** prior to ass
31d80 69 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 74 72 igning a new str
31d90 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 ing to zErrMsg.
31da0 20 41 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 After the error
31db0 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 20 64 message.** is d
31dc0 65 6c 69 76 65 72 65 64 20 75 70 20 74 6f 20 74 elivered up to t
31dd0 68 65 20 63 6c 69 65 6e 74 20 61 70 70 6c 69 63 he client applic
31de0 61 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e ation, the strin
31df0 67 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 g will be automa
31e00 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 tically.** freed
31e10 20 62 79 20 73 71 6c 69 74 65 33 5f 66 72 65 65 by sqlite3_free
31e20 28 29 20 61 6e 64 20 74 68 65 20 7a 45 72 72 4d () and the zErrM
31e30 73 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 62 65 sg field will be
31e40 20 7a 65 72 6f 65 64 2e 0a 2a 2f 0a 73 74 72 75 zeroed..*/.stru
31e50 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 ct sqlite3_vtab
31e60 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 {. const sqlite
31e70 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 3_module *pModul
31e80 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c e; /* The modul
31e90 65 20 66 6f 72 20 74 68 69 73 20 76 69 72 74 75 e for this virtu
31ea0 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e al table */. in
31eb0 74 20 6e 52 65 66 3b 20 20 20 20 20 20 20 20 20 t nRef;
31ec0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
31ed0 20 4e 4f 20 4c 4f 4e 47 45 52 20 55 53 45 44 20 NO LONGER USED
31ee0 2a 2f 0a 20 20 63 68 61 72 20 2a 7a 45 72 72 4d */. char *zErrM
31ef0 73 67 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 sg;
31f00 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 65 /* Error me
31f10 73 73 61 67 65 20 66 72 6f 6d 20 73 71 6c 69 74 ssage from sqlit
31f20 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 2a 2f 0a e3_mprintf() */.
31f30 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 /* Virtual tab
31f40 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
31f50 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c ns will typicall
31f60 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c y add additional
31f70 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f fields */.};../
31f80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 *.** CAPI3REF: V
31f90 69 72 74 75 61 6c 20 54 61 62 6c 65 20 43 75 72 irtual Table Cur
31fa0 73 6f 72 20 4f 62 6a 65 63 74 20 20 7b 48 31 38 sor Object {H18
31fb0 30 32 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 020} <S20400>.**
31fc0 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 KEYWORDS: sqlit
31fd0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b e3_vtab_cursor {
31fe0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 63 75 virtual table cu
31ff0 72 73 6f 72 7d 0a 2a 2a 20 45 58 50 45 52 49 4d rsor}.** EXPERIM
32000 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 45 76 65 72 ENTAL.**.** Ever
32010 79 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 y [virtual table
32020 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 module] impleme
32030 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73 ntation uses a s
32040 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a ubclass of the.*
32050 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 * following stru
32060 63 74 75 72 65 20 74 6f 20 64 65 73 63 72 69 62 cture to describ
32070 65 20 63 75 72 73 6f 72 73 20 74 68 61 74 20 70 e cursors that p
32080 6f 69 6e 74 20 69 6e 74 6f 20 74 68 65 0a 2a 2a oint into the.**
32090 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d [virtual table]
320a0 20 61 6e 64 20 61 72 65 20 75 73 65 64 0a 2a 2a and are used.**
320b0 20 74 6f 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68 to loop through
320c0 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 the virtual tab
320d0 6c 65 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65 le. Cursors are
320e0 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 74 created using t
320f0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d he.** [sqlite3_m
32100 6f 64 75 6c 65 2e 78 4f 70 65 6e 20 7c 20 78 4f odule.xOpen | xO
32110 70 65 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 pen] method of t
32120 68 65 20 6d 6f 64 75 6c 65 20 61 6e 64 20 61 72 he module and ar
32130 65 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 62 e destroyed.** b
32140 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d y the [sqlite3_m
32150 6f 64 75 6c 65 2e 78 43 6c 6f 73 65 20 7c 20 78 odule.xClose | x
32160 43 6c 6f 73 65 5d 20 6d 65 74 68 6f 64 2e 20 20 Close] method.
32170 43 75 73 73 6f 72 73 20 61 72 65 20 75 73 65 64 Cussors are used
32180 0a 2a 2a 20 62 79 20 74 68 65 20 5b 78 46 69 6c .** by the [xFil
32190 74 65 72 5d 2c 20 5b 78 4e 65 78 74 5d 2c 20 5b ter], [xNext], [
321a0 78 45 6f 66 5d 2c 20 5b 78 43 6f 6c 75 6d 6e 5d xEof], [xColumn]
321b0 2c 20 61 6e 64 20 5b 78 52 6f 77 69 64 5d 20 6d , and [xRowid] m
321c0 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 74 68 65 ethods.** of the
321d0 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 6d module. Each m
321e0 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 odule implementa
321f0 74 69 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65 tion will define
32200 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 .** the content
32210 6f 66 20 61 20 63 75 72 73 6f 72 20 73 74 72 75 of a cursor stru
32220 63 74 75 72 65 20 74 6f 20 73 75 69 74 20 69 74 cture to suit it
32230 73 20 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a s own needs..**.
32240 2a 2a 20 54 68 69 73 20 73 75 70 65 72 63 6c 61 ** This supercla
32250 73 73 20 65 78 69 73 74 73 20 69 6e 20 6f 72 64 ss exists in ord
32260 65 72 20 74 6f 20 64 65 66 69 6e 65 20 66 69 65 er to define fie
32270 6c 64 73 20 6f 66 20 74 68 65 20 63 75 72 73 6f lds of the curso
32280 72 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f r that.** are co
32290 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c mmon to all impl
322a0 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a ementations..*/.
322b0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 struct sqlite3_v
322c0 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73 tab_cursor {. s
322d0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 qlite3_vtab *pVt
322e0 61 62 3b 20 20 20 20 20 20 2f 2a 20 56 69 72 74 ab; /* Virt
322f0 75 61 6c 20 74 61 62 6c 65 20 6f 66 20 74 68 69 ual table of thi
32300 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a s cursor */. /*
32310 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 Virtual table i
32320 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 mplementations w
32330 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 ill typically ad
32340 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 d additional fie
32350 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a lds */.};../*.**
32360 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 CAPI3REF: Decla
32370 72 65 20 54 68 65 20 53 63 68 65 6d 61 20 4f 66 re The Schema Of
32380 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 A Virtual Table
32390 20 7b 48 31 38 32 38 30 7d 20 3c 53 32 30 34 30 {H18280} <S2040
323a0 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 0>.** EXPERIMENT
323b0 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 78 43 AL.**.** The [xC
323c0 72 65 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e reate] and [xCon
323d0 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 nect] methods of
323e0 20 61 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 a.** [virtual t
323f0 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 63 61 6c able module] cal
32400 6c 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 l this interface
32410 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72 65 20 74 .** to declare t
32420 68 65 20 66 6f 72 6d 61 74 20 28 74 68 65 20 6e he format (the n
32430 61 6d 65 73 20 61 6e 64 20 64 61 74 61 74 79 70 ames and datatyp
32440 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e es of the column
32450 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20 76 69 72 s) of.** the vir
32460 74 75 61 6c 20 74 61 62 6c 65 73 20 74 68 65 79 tual tables they
32470 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 53 implement..*/.S
32480 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
32490 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e _EXPERIMENTAL in
324a0 74 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 t sqlite3_declar
324b0 65 5f 76 74 61 62 28 73 71 6c 69 74 65 33 2a 2c e_vtab(sqlite3*,
324c0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 51 const char *zSQ
324d0 4c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 L);../*.** CAPI3
324e0 52 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20 41 20 REF: Overload A
324f0 46 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41 20 56 Function For A V
32500 69 72 74 75 61 6c 20 54 61 62 6c 65 20 7b 48 31 irtual Table {H1
32510 38 33 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 8300} <S20400>.*
32520 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a * EXPERIMENTAL.*
32530 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 *.** Virtual tab
32540 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64 65 20 les can provide
32550 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70 6c alternative impl
32560 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66 ementations of f
32570 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e unctions.** usin
32580 67 20 74 68 65 20 5b 78 46 69 6e 64 46 75 6e 63 g the [xFindFunc
32590 74 69 6f 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 tion] method of
325a0 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62 the [virtual tab
325b0 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 0a 2a 2a le module]. .**
325c0 20 42 75 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 But global vers
325d0 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20 66 75 ions of those fu
325e0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 nctions.** must
325f0 65 78 69 73 74 20 69 6e 20 6f 72 64 65 72 20 74 exist in order t
32600 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e o be overloaded.
32610 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 .**.** This API
32620 6d 61 6b 65 73 20 73 75 72 65 20 61 20 67 6c 6f makes sure a glo
32630 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 bal version of a
32640 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 function with a
32650 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e particular.** n
32660 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f ame and number o
32670 66 20 70 61 72 61 6d 65 74 65 72 73 20 65 78 69 f parameters exi
32680 73 74 73 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 sts. If no such
32690 20 66 75 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 function exists
326a0 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 69 73 20 .** before this
326b0 41 50 49 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 API is called, a
326c0 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 new function is
326d0 20 63 72 65 61 74 65 64 2e 20 20 54 68 65 20 69 created. The i
326e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a mplementation.**
326f0 20 6f 66 20 74 68 65 20 6e 65 77 20 66 75 6e 63 of the new func
32700 74 69 6f 6e 20 61 6c 77 61 79 73 20 63 61 75 73 tion always caus
32710 65 73 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 es an exception
32720 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 to be thrown. S
32730 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66 75 6e o.** the new fun
32740 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f ction is not goo
32750 64 20 66 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 d for anything b
32760 79 20 69 74 73 65 6c 66 2e 20 20 49 74 73 20 6f y itself. Its o
32770 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 nly.** purpose i
32780 73 20 74 6f 20 62 65 20 61 20 70 6c 61 63 65 68 s to be a placeh
32790 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 older function t
327a0 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 6c hat can be overl
327b0 6f 61 64 65 64 0a 2a 2a 20 62 79 20 61 20 5b 76 oaded.** by a [v
327c0 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a irtual table]..*
327d0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c /.SQLITE_API SQL
327e0 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c ITE_EXPERIMENTAL
327f0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 76 65 int sqlite3_ove
32800 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e 28 73 rload_function(s
32810 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 qlite3*, const c
32820 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 har *zFuncName,
32830 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a int nArg);../*.*
32840 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 * The interface
32850 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 to the virtual-t
32860 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 64 able mechanism d
32870 65 66 69 6e 65 64 20 61 62 6f 76 65 20 28 62 61 efined above (ba
32880 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20 63 6f ck up.** to a co
32890 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62 6c 79 mment remarkably
328a0 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 69 73 similar to this
328b0 20 6f 6e 65 29 20 69 73 20 63 75 72 72 65 6e 74 one) is current
328c0 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a ly considered.**
328d0 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e to be experimen
328e0 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 tal. The interf
328f0 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 ace might change
32900 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 in incompatible
32910 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 ways..** If thi
32920 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 s is a problem f
32930 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 or you, do not u
32940 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 se the interface
32950 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a at this time..*
32960 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 *.** When the vi
32970 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 rtual-table mech
32980 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 anism stabilizes
32990 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 , we will declar
329a0 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 e the.** interfa
329b0 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 ce fixed, suppor
329c0 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c t it indefinitel
329d0 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 y, and remove th
329e0 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a 0a 2a is comment..**.*
329f0 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 ***** EXPERIMENT
32a00 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 AL - subject to
32a10 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e change without n
32a20 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a otice **********
32a30 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 ****.*/../*.** C
32a40 41 50 49 33 52 45 46 3a 20 41 20 48 61 6e 64 6c API3REF: A Handl
32a50 65 20 54 6f 20 41 6e 20 4f 70 65 6e 20 42 4c 4f e To An Open BLO
32a60 42 20 7b 48 31 37 38 30 30 7d 20 3c 53 33 30 32 B {H17800} <S302
32a70 33 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 30>.** KEYWORDS:
32a80 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 7d 20 7b {BLOB handle} {
32a90 42 4c 4f 42 20 68 61 6e 64 6c 65 73 7d 0a 2a 2a BLOB handles}.**
32aa0 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 .** An instance
32ab0 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 of this object r
32ac0 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 epresents an ope
32ad0 6e 20 42 4c 4f 42 20 6f 6e 20 77 68 69 63 68 0a n BLOB on which.
32ae0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 ** [sqlite3_blob
32af0 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e _open | incremen
32b00 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 63 61 tal BLOB I/O] ca
32b10 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 2e 0a n be performed..
32b20 2a 2a 20 4f 62 6a 65 63 74 73 20 6f 66 20 74 68 ** Objects of th
32b30 69 73 20 74 79 70 65 20 61 72 65 20 63 72 65 61 is type are crea
32b40 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ted by [sqlite3_
32b50 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 blob_open()].**
32b60 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20 62 79 and destroyed by
32b70 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 [sqlite3_blob_c
32b80 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 lose()]..** The
32b90 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 [sqlite3_blob_re
32ba0 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 ad()] and [sqlit
32bb0 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d e3_blob_write()]
32bc0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 63 interfaces.** c
32bd0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 an be used to re
32be0 61 64 20 6f 72 20 77 72 69 74 65 20 73 6d 61 6c ad or write smal
32bf0 6c 20 73 75 62 73 65 63 74 69 6f 6e 73 20 6f 66 l subsections of
32c00 20 74 68 65 20 42 4c 4f 42 2e 0a 2a 2a 20 54 68 the BLOB..** Th
32c10 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f e [sqlite3_blob_
32c20 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 bytes()] interfa
32c30 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 ce returns the s
32c40 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 ize of the BLOB
32c50 69 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 in bytes..*/.typ
32c60 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
32c70 74 65 33 5f 62 6c 6f 62 20 73 71 6c 69 74 65 33 te3_blob sqlite3
32c80 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 _blob;../*.** CA
32c90 50 49 33 52 45 46 3a 20 4f 70 65 6e 20 41 20 42 PI3REF: Open A B
32ca0 4c 4f 42 20 46 6f 72 20 49 6e 63 72 65 6d 65 6e LOB For Incremen
32cb0 74 61 6c 20 49 2f 4f 20 7b 48 31 37 38 31 30 7d tal I/O {H17810}
32cc0 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 <S30230>.**.**
32cd0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 73 20 This interfaces
32ce0 6f 70 65 6e 73 20 61 20 5b 42 4c 4f 42 20 68 61 opens a [BLOB ha
32cf0 6e 64 6c 65 20 7c 20 68 61 6e 64 6c 65 5d 20 74 ndle | handle] t
32d00 6f 20 74 68 65 20 42 4c 4f 42 20 6c 6f 63 61 74 o the BLOB locat
32d10 65 64 0a 2a 2a 20 69 6e 20 72 6f 77 20 69 52 6f ed.** in row iRo
32d20 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d w, column zColum
32d30 6e 2c 20 74 61 62 6c 65 20 7a 54 61 62 6c 65 20 n, table zTable
32d40 69 6e 20 64 61 74 61 62 61 73 65 20 7a 44 62 3b in database zDb;
32d50 0a 2a 2a 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 .** in other wor
32d60 64 73 2c 20 74 68 65 20 73 61 6d 65 20 42 4c 4f ds, the same BLO
32d70 42 20 74 68 61 74 20 77 6f 75 6c 64 20 62 65 20 B that would be
32d80 73 65 6c 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a selected by:.**.
32d90 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 ** <pre>.**
32da0 53 45 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 SELECT zColumn F
32db0 52 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57 ROM zDb.zTable W
32dc0 48 45 52 45 20 5b 72 6f 77 69 64 5d 20 3d 20 69 HERE [rowid] = i
32dd0 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 20 7b Row;.** </pre> {
32de0 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 END}.**.** If th
32df0 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 e flags paramete
32e00 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 r is non-zero, t
32e10 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69 73 20 hen the BLOB is
32e20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 0a opened for read.
32e30 2a 2a 20 61 6e 64 20 77 72 69 74 65 20 61 63 63 ** and write acc
32e40 65 73 73 2e 20 49 66 20 69 74 20 69 73 20 7a 65 ess. If it is ze
32e50 72 6f 2c 20 74 68 65 20 42 4c 4f 42 20 69 73 20 ro, the BLOB is
32e60 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 20 opened for read
32e70 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f access..**.** No
32e80 74 65 20 74 68 61 74 20 74 68 65 20 64 61 74 61 te that the data
32e90 62 61 73 65 20 6e 61 6d 65 20 69 73 20 6e 6f 74 base name is not
32ea0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 74 68 the filename th
32eb0 61 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 at contains.** t
32ec0 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74 20 he database but
32ed0 72 61 74 68 65 72 20 74 68 65 20 73 79 6d 62 6f rather the symbo
32ee0 6c 69 63 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 lic name of the
32ef0 64 61 74 61 62 61 73 65 20 74 68 61 74 0a 2a 2a database that.**
32f00 20 69 73 20 61 73 73 69 67 6e 65 64 20 77 68 65 is assigned whe
32f10 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 n the database i
32f20 73 20 63 6f 6e 6e 65 63 74 65 64 20 75 73 69 6e s connected usin
32f30 67 20 5b 41 54 54 41 43 48 5d 2e 0a 2a 2a 20 46 g [ATTACH]..** F
32f40 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 or the main data
32f50 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65 20 64 base file, the d
32f60 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 atabase name is
32f70 22 6d 61 69 6e 22 2e 0a 2a 2a 20 46 6f 72 20 54 "main"..** For T
32f80 45 4d 50 20 74 61 62 6c 65 73 2c 20 74 68 65 20 EMP tables, the
32f90 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 database name is
32fa0 20 22 74 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20 4f "temp"..**.** O
32fb0 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 n success, [SQLI
32fc0 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e TE_OK] is return
32fd0 65 64 20 61 6e 64 20 74 68 65 20 6e 65 77 20 5b ed and the new [
32fe0 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 73 20 BLOB handle] is
32ff0 77 72 69 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70 written.** to *p
33000 70 42 6c 6f 62 2e 20 4f 74 68 65 72 77 69 73 65 pBlob. Otherwise
33010 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d an [error code]
33020 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 is returned and
33030 20 2a 70 70 42 6c 6f 62 20 69 73 20 73 65 74 0a *ppBlob is set.
33040 2a 2a 20 74 6f 20 62 65 20 61 20 6e 75 6c 6c 20 ** to be a null
33050 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68 69 73 pointer..** This
33060 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 74 function sets t
33070 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
33080 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72 20 63 nection] error c
33090 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 0a ode and message.
330a0 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 ** accessible vi
330b0 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f a [sqlite3_errco
330c0 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 de()] and [sqlit
330d0 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 e3_errmsg()] and
330e0 20 72 65 6c 61 74 65 64 0a 2a 2a 20 66 75 6e 63 related.** func
330f0 74 69 6f 6e 73 2e 20 20 4e 6f 74 65 20 74 68 61 tions. Note tha
33100 74 20 74 68 65 20 2a 70 70 42 6c 6f 62 20 76 61 t the *ppBlob va
33110 72 69 61 62 6c 65 20 69 73 20 61 6c 77 61 79 73 riable is always
33120 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 69 6e 20 initialized in
33130 61 0a 2a 2a 20 77 61 79 20 74 68 61 74 20 6d 61 a.** way that ma
33140 6b 65 73 20 69 74 20 73 61 66 65 20 74 6f 20 69 kes it safe to i
33150 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 62 nvoke [sqlite3_b
33160 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 20 6f 6e 20 lob_close()] on
33170 2a 70 70 42 6c 6f 62 0a 2a 2a 20 72 65 67 61 72 *ppBlob.** regar
33180 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 dless of the suc
33190 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 20 cess or failure
331a0 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e of this routine.
331b0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 6f .**.** If the ro
331c0 77 20 74 68 61 74 20 61 20 42 4c 4f 42 20 68 61 w that a BLOB ha
331d0 6e 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 ndle points to i
331e0 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 61 6e s modified by an
331f0 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20 5b 44 .** [UPDATE], [D
33200 45 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20 5b 4f ELETE], or by [O
33210 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69 64 65 N CONFLICT] side
33220 2d 65 66 66 65 63 74 73 0a 2a 2a 20 74 68 65 6e -effects.** then
33230 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 the BLOB handle
33240 20 69 73 20 6d 61 72 6b 65 64 20 61 73 20 22 65 is marked as "e
33250 78 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68 69 73 xpired"..** This
33260 20 69 73 20 74 72 75 65 20 69 66 20 61 6e 79 20 is true if any
33270 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 6f column of the ro
33280 77 20 69 73 20 63 68 61 6e 67 65 64 2c 20 65 76 w is changed, ev
33290 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6f en a column.** o
332a0 74 68 65 72 20 74 68 61 6e 20 74 68 65 20 6f 6e ther than the on
332b0 65 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c e the BLOB handl
332c0 65 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 0a 2a 2a e is open on..**
332d0 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 Calls to [sqlit
332e0 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 e3_blob_read()]
332f0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f and [sqlite3_blo
33300 62 5f 77 72 69 74 65 28 29 5d 20 66 6f 72 0a 2a b_write()] for.*
33310 2a 20 61 20 65 78 70 69 72 65 64 20 42 4c 4f 42 * a expired BLOB
33320 20 68 61 6e 64 6c 65 20 66 61 69 6c 20 77 69 74 handle fail wit
33330 68 20 61 6e 20 72 65 74 75 72 6e 20 63 6f 64 65 h an return code
33340 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 of [SQLITE_ABOR
33350 54 5d 2e 0a 2a 2a 20 43 68 61 6e 67 65 73 20 77 T]..** Changes w
33360 72 69 74 74 65 6e 20 69 6e 74 6f 20 61 20 42 4c ritten into a BL
33370 4f 42 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 OB prior to the
33380 42 4c 4f 42 20 65 78 70 69 72 69 6e 67 20 61 72 BLOB expiring ar
33390 65 20 6e 6f 74 0a 2a 2a 20 72 6f 6c 6c 62 61 63 e not.** rollbac
333a0 6b 20 62 79 20 74 68 65 20 65 78 70 69 72 61 74 k by the expirat
333b0 69 6f 6e 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e ion of the BLOB.
333c0 20 20 53 75 63 68 20 63 68 61 6e 67 65 73 20 77 Such changes w
333d0 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a ill eventually.*
333e0 2a 20 63 6f 6d 6d 69 74 20 69 66 20 74 68 65 20 * commit if the
333f0 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 transaction cont
33400 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 inues to complet
33410 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 73 65 20 74 ion..**.** Use t
33420 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 he [sqlite3_blob
33430 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 _bytes()] interf
33440 61 63 65 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 ace to determine
33450 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 the size of.**
33460 74 68 65 20 6f 70 65 6e 65 64 20 62 6c 6f 62 2e the opened blob.
33470 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 61 20 The size of a
33480 62 6c 6f 62 20 6d 61 79 20 6e 6f 74 20 62 65 20 blob may not be
33490 63 68 61 6e 67 65 64 20 62 79 20 74 68 69 73 0a changed by this.
334a0 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 20 55 ** interface. U
334b0 73 65 20 74 68 65 20 5b 55 50 44 41 54 45 5d 20 se the [UPDATE]
334c0 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f 20 63 SQL command to c
334d0 68 61 6e 67 65 20 74 68 65 20 73 69 7a 65 20 6f hange the size o
334e0 66 20 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a 0a f a.** blob..**.
334f0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f ** The [sqlite3_
33500 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d bind_zeroblob()]
33510 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 and [sqlite3_re
33520 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d sult_zeroblob()]
33530 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 interfaces.** a
33540 6e 64 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 nd the built-in
33550 5b 7a 65 72 6f 62 6c 6f 62 5d 20 53 51 4c 20 66 [zeroblob] SQL f
33560 75 6e 63 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 unction can be u
33570 73 65 64 2c 20 69 66 20 64 65 73 69 72 65 64 2c sed, if desired,
33580 0a 2a 2a 20 74 6f 20 63 72 65 61 74 65 20 61 6e .** to create an
33590 20 65 6d 70 74 79 2c 20 7a 65 72 6f 2d 66 69 6c empty, zero-fil
335a0 6c 65 64 20 62 6c 6f 62 20 69 6e 20 77 68 69 63 led blob in whic
335b0 68 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69 h to read or wri
335c0 74 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68 69 73 te using.** this
335d0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a interface..**.*
335e0 2a 20 54 6f 20 61 76 6f 69 64 20 61 20 72 65 73 * To avoid a res
335f0 6f 75 72 63 65 20 6c 65 61 6b 2c 20 65 76 65 72 ource leak, ever
33600 79 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e y open [BLOB han
33610 64 6c 65 5d 20 73 68 6f 75 6c 64 20 65 76 65 6e dle] should even
33620 74 75 61 6c 6c 79 0a 2a 2a 20 62 65 20 72 65 6c tually.** be rel
33630 65 61 73 65 64 20 62 79 20 61 20 63 61 6c 6c 20 eased by a call
33640 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 to [sqlite3_blob
33650 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a _close()]..**.**
33660 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
33670 2a 20 5b 48 31 37 38 31 33 5d 20 5b 48 31 37 38 * [H17813] [H178
33680 31 34 5d 20 5b 48 31 37 38 31 36 5d 20 5b 48 31 14] [H17816] [H1
33690 37 38 31 39 5d 20 5b 48 31 37 38 32 31 5d 20 5b 7819] [H17821] [
336a0 48 31 37 38 32 34 5d 0a 2a 2f 0a 53 51 4c 49 54 H17824].*/.SQLIT
336b0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
336c0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 3_blob_open(. s
336d0 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 qlite3*,. const
336e0 20 63 68 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f char *zDb,. co
336f0 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 nst char *zTable
33700 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a ,. const char *
33710 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 zColumn,. sqlit
33720 65 33 5f 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20 e3_int64 iRow,.
33730 20 69 6e 74 20 66 6c 61 67 73 2c 0a 20 20 73 71 int flags,. sq
33740 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 lite3_blob **ppB
33750 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 lob.);../*.** CA
33760 50 49 33 52 45 46 3a 20 43 6c 6f 73 65 20 41 20 PI3REF: Close A
33770 42 4c 4f 42 20 48 61 6e 64 6c 65 20 7b 48 31 37 BLOB Handle {H17
33780 38 33 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 830} <S30230>.**
33790 0a 2a 2a 20 43 6c 6f 73 65 73 20 61 6e 20 6f 70 .** Closes an op
337a0 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d en [BLOB handle]
337b0 2e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 69 6e 67 20 ..**.** Closing
337c0 61 20 42 4c 4f 42 20 73 68 61 6c 6c 20 63 61 75 a BLOB shall cau
337d0 73 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 se the current t
337e0 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 63 6f ransaction to co
337f0 6d 6d 69 74 0a 2a 2a 20 69 66 20 74 68 65 72 65 mmit.** if there
33800 20 61 72 65 20 6e 6f 20 6f 74 68 65 72 20 42 4c are no other BL
33810 4f 42 73 2c 20 6e 6f 20 70 65 6e 64 69 6e 67 20 OBs, no pending
33820 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
33830 6e 74 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 nts, and the.**
33840 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
33850 69 6f 6e 20 69 73 20 69 6e 20 5b 61 75 74 6f 63 ion is in [autoc
33860 6f 6d 6d 69 74 20 6d 6f 64 65 5d 2e 0a 2a 2a 20 ommit mode]..**
33870 49 66 20 61 6e 79 20 77 72 69 74 65 73 20 77 65 If any writes we
33880 72 65 20 6d 61 64 65 20 74 6f 20 74 68 65 20 42 re made to the B
33890 4c 4f 42 2c 20 74 68 65 79 20 6d 69 67 68 74 20 LOB, they might
338a0 62 65 20 68 65 6c 64 20 69 6e 20 63 61 63 68 65 be held in cache
338b0 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20 63 6c .** until the cl
338c0 6f 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 66 ose operation if
338d0 20 74 68 65 79 20 77 69 6c 6c 20 66 69 74 2e 0a they will fit..
338e0 2a 2a 0a 2a 2a 20 43 6c 6f 73 69 6e 67 20 74 68 **.** Closing th
338f0 65 20 42 4c 4f 42 20 6f 66 74 65 6e 20 66 6f 72 e BLOB often for
33900 63 65 73 20 74 68 65 20 63 68 61 6e 67 65 73 0a ces the changes.
33910 2a 2a 20 6f 75 74 20 74 6f 20 64 69 73 6b 20 61 ** out to disk a
33920 6e 64 20 73 6f 20 69 66 20 61 6e 79 20 49 2f 4f nd so if any I/O
33930 20 65 72 72 6f 72 73 20 6f 63 63 75 72 2c 20 74 errors occur, t
33940 68 65 79 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 hey will likely
33950 6f 63 63 75 72 0a 2a 2a 20 61 74 20 74 68 65 20 occur.** at the
33960 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 42 4c time when the BL
33970 4f 42 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 41 OB is closed. A
33980 6e 79 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f ny errors that o
33990 63 63 75 72 20 64 75 72 69 6e 67 0a 2a 2a 20 63 ccur during.** c
339a0 6c 6f 73 69 6e 67 20 61 72 65 20 72 65 70 6f 72 losing are repor
339b0 74 65 64 20 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 ted as a non-zer
339c0 6f 20 72 65 74 75 72 6e 20 76 61 6c 75 65 2e 0a o return value..
339d0 2a 2a 0a 2a 2a 20 54 68 65 20 42 4c 4f 42 20 69 **.** The BLOB i
339e0 73 20 63 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 69 s closed uncondi
339f0 74 69 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 6e 20 tionally. Even
33a00 69 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 if this routine
33a10 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 72 returns.** an er
33a20 72 6f 72 20 63 6f 64 65 2c 20 74 68 65 20 42 4c ror code, the BL
33a30 4f 42 20 69 73 20 73 74 69 6c 6c 20 63 6c 6f 73 OB is still clos
33a40 65 64 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e ed..**.** Callin
33a50 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 g this routine w
33a60 69 74 68 20 61 20 6e 75 6c 6c 20 70 6f 69 6e 74 ith a null point
33a70 65 72 20 28 77 68 69 63 68 20 61 73 20 77 6f 75 er (which as wou
33a80 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 0a 2a ld be returned.*
33a90 2a 20 62 79 20 66 61 69 6c 65 64 20 63 61 6c 6c * by failed call
33aa0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f to [sqlite3_blo
33ab0 62 5f 6f 70 65 6e 28 29 5d 29 20 69 73 20 61 20 b_open()]) is a
33ac0 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a harmless no-op..
33ad0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
33ae0 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 33 33 5d 20 ts:.** [H17833]
33af0 5b 48 31 37 38 33 36 5d 20 5b 48 31 37 38 33 39 [H17836] [H17839
33b00 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
33b10 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 int sqlite3_blob
33b20 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 5f 62 _close(sqlite3_b
33b30 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 lob *);../*.** C
33b40 41 50 49 33 52 45 46 3a 20 52 65 74 75 72 6e 20 API3REF: Return
33b50 54 68 65 20 53 69 7a 65 20 4f 66 20 41 6e 20 4f The Size Of An O
33b60 70 65 6e 20 42 4c 4f 42 20 7b 48 31 37 38 34 30 pen BLOB {H17840
33b70 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a } <S30230>.**.**
33b80 20 52 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a Returns the siz
33b90 65 20 69 6e 20 62 79 74 65 73 20 6f 66 20 74 68 e in bytes of th
33ba0 65 20 42 4c 4f 42 20 61 63 63 65 73 73 69 62 6c e BLOB accessibl
33bb0 65 20 76 69 61 20 74 68 65 20 0a 2a 2a 20 73 75 e via the .** su
33bc0 63 63 65 73 73 66 75 6c 6c 79 20 6f 70 65 6e 65 ccessfully opene
33bd0 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 d [BLOB handle]
33be0 69 6e 20 69 74 73 20 6f 6e 6c 79 20 61 72 67 75 in its only argu
33bf0 6d 65 6e 74 2e 20 20 54 68 65 0a 2a 2a 20 69 6e ment. The.** in
33c00 63 72 65 6d 65 6e 74 61 6c 20 62 6c 6f 62 20 49 cremental blob I
33c10 2f 4f 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 /O routines can
33c20 6f 6e 6c 79 20 72 65 61 64 20 6f 72 20 6f 76 65 only read or ove
33c30 72 77 72 69 74 69 6e 67 20 65 78 69 73 74 69 6e rwriting existin
33c40 67 0a 2a 2a 20 62 6c 6f 62 20 63 6f 6e 74 65 6e g.** blob conten
33c50 74 3b 20 74 68 65 79 20 63 61 6e 6e 6f 74 20 63 t; they cannot c
33c60 68 61 6e 67 65 20 74 68 65 20 73 69 7a 65 20 6f hange the size o
33c70 66 20 61 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 f a blob..**.**
33c80 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c This routine onl
33c90 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c y works on a [BL
33ca0 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 OB handle] which
33cb0 20 68 61 73 20 62 65 65 6e 20 63 72 65 61 74 65 has been create
33cc0 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20 d.** by a prior
33cd0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 successful call
33ce0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 to [sqlite3_blob
33cf0 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 _open()] and whi
33d00 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 ch has not.** be
33d10 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 en closed by [sq
33d20 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 lite3_blob_close
33d30 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e ()]. Passing an
33d40 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20 y other pointer
33d50 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f in.** to this ro
33d60 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e utine results in
33d70 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 undefined and p
33d80 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 robably undesira
33d90 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a ble behavior..**
33da0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
33db0 3a 0a 2a 2a 20 5b 48 31 37 38 34 33 5d 0a 2a 2f :.** [H17843].*/
33dc0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
33dd0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 sqlite3_blob_byt
33de0 65 73 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 es(sqlite3_blob
33df0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
33e00 52 45 46 3a 20 52 65 61 64 20 44 61 74 61 20 46 REF: Read Data F
33e10 72 6f 6d 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 rom A BLOB Incre
33e20 6d 65 6e 74 61 6c 6c 79 20 7b 48 31 37 38 35 30 mentally {H17850
33e30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a } <S30230>.**.**
33e40 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 This function i
33e50 73 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 64 s used to read d
33e60 61 74 61 20 66 72 6f 6d 20 61 6e 20 6f 70 65 6e ata from an open
33e70 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 [BLOB handle] i
33e80 6e 74 6f 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d nto a.** caller-
33e90 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e supplied buffer.
33ea0 20 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 N bytes of data
33eb0 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f are copied into
33ec0 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20 66 72 6f buffer Z.** fro
33ed0 6d 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c m the open BLOB,
33ee0 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 starting at off
33ef0 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a set iOffset..**.
33f00 2a 2a 20 49 66 20 6f 66 66 73 65 74 20 69 4f 66 ** If offset iOf
33f10 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 fset is less tha
33f20 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 n N bytes from t
33f30 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c he end of the BL
33f40 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 OB,.** [SQLITE_E
33f50 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 RROR] is returne
33f60 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 d and no data is
33f70 20 72 65 61 64 2e 20 20 49 66 20 4e 20 6f 72 20 read. If N or
33f80 69 4f 66 66 73 65 74 20 69 73 0a 2a 2a 20 6c 65 iOffset is.** le
33f90 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 5b 53 ss than zero, [S
33fa0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 QLITE_ERROR] is
33fb0 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 returned and no
33fc0 64 61 74 61 20 69 73 20 72 65 61 64 2e 0a 2a 2a data is read..**
33fd0 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 The size of the
33fe0 20 62 6c 6f 62 20 28 61 6e 64 20 68 65 6e 63 65 blob (and hence
33ff0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c the maximum val
34000 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65 74 29 ue of N+iOffset)
34010 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 .** can be deter
34020 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20 mined using the
34030 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 [sqlite3_blob_by
34040 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 tes()] interface
34050 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 74 74 65 6d ..**.** An attem
34060 70 74 20 74 6f 20 72 65 61 64 20 66 72 6f 6d 20 pt to read from
34070 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c 4f 42 an expired [BLOB
34080 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77 handle] fails w
34090 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 ith an.** error
340a0 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f code of [SQLITE_
340b0 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 4f 6e ABORT]..**.** On
340c0 20 73 75 63 63 65 73 73 2c 20 53 51 4c 49 54 45 success, SQLITE
340d0 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e _OK is returned.
340e0 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 61 .** Otherwise, a
340f0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f n [error code] o
34100 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 65 r an [extended e
34110 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 rror code] is re
34120 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 turned..**.** Th
34130 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 is routine only
34140 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 works on a [BLOB
34150 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 handle] which h
34160 61 73 20 62 65 65 6e 20 63 72 65 61 74 65 64 0a as been created.
34170 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73 75 ** by a prior su
34180 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f ccessful call to
34190 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f [sqlite3_blob_o
341a0 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 68 pen()] and which
341b0 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e has not.** been
341c0 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 closed by [sqli
341d0 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 te3_blob_close()
341e0 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79 20 ]. Passing any
341f0 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69 6e other pointer in
34200 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 74 .** to this rout
34210 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20 75 ine results in u
34220 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f ndefined and pro
34230 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c bably undesirabl
34240 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a e behavior..**.*
34250 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
34260 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 ite3_blob_write(
34270 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 )]..**.** Requir
34280 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 ements:.** [H178
34290 35 33 5d 20 5b 48 31 37 38 35 36 5d 20 5b 48 31 53] [H17856] [H1
342a0 37 38 35 39 5d 20 5b 48 31 37 38 36 32 5d 20 5b 7859] [H17862] [
342b0 48 31 37 38 36 33 5d 20 5b 48 31 37 38 36 35 5d H17863] [H17865]
342c0 20 5b 48 31 37 38 36 38 5d 0a 2a 2f 0a 53 51 4c [H17868].*/.SQL
342d0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
342e0 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 73 71 te3_blob_read(sq
342f0 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 76 6f lite3_blob *, vo
34300 69 64 20 2a 5a 2c 20 69 6e 74 20 4e 2c 20 69 6e id *Z, int N, in
34310 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a t iOffset);../*.
34320 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 57 72 69 ** CAPI3REF: Wri
34330 74 65 20 44 61 74 61 20 49 6e 74 6f 20 41 20 42 te Data Into A B
34340 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c LOB Incrementall
34350 79 20 7b 48 31 37 38 37 30 7d 20 3c 53 33 30 32 y {H17870} <S302
34360 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 30>.**.** This f
34370 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20 unction is used
34380 74 6f 20 77 72 69 74 65 20 64 61 74 61 20 69 6e to write data in
34390 74 6f 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 to an open [BLOB
343a0 20 68 61 6e 64 6c 65 5d 20 66 72 6f 6d 20 61 0a handle] from a.
343b0 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70 6c 69 ** caller-suppli
343c0 65 64 20 62 75 66 66 65 72 2e 20 4e 20 62 79 74 ed buffer. N byt
343d0 65 73 20 6f 66 20 64 61 74 61 20 61 72 65 20 63 es of data are c
343e0 6f 70 69 65 64 20 66 72 6f 6d 20 74 68 65 20 62 opied from the b
343f0 75 66 66 65 72 20 5a 0a 2a 2a 20 69 6e 74 6f 20 uffer Z.** into
34400 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 the open BLOB, s
34410 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65 tarting at offse
34420 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a t iOffset..**.**
34430 20 49 66 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 If the [BLOB ha
34440 6e 64 6c 65 5d 20 70 61 73 73 65 64 20 61 73 20 ndle] passed as
34450 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
34460 6e 74 20 77 61 73 20 6e 6f 74 20 6f 70 65 6e 65 nt was not opene
34470 64 20 66 6f 72 0a 2a 2a 20 77 72 69 74 69 6e 67 d for.** writing
34480 20 28 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 (the flags para
34490 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 meter to [sqlite
344a0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 77 3_blob_open()] w
344b0 61 73 20 7a 65 72 6f 29 2c 0a 2a 2a 20 74 68 69 as zero),.** thi
344c0 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 s function retur
344d0 6e 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 4f ns [SQLITE_READO
344e0 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 NLY]..**.** This
344f0 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6f 6e function may on
34500 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 63 6f ly modify the co
34510 6e 74 65 6e 74 73 20 6f 66 20 74 68 65 20 42 4c ntents of the BL
34520 4f 42 3b 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 OB; it is.** not
34530 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 63 possible to inc
34540 72 65 61 73 65 20 74 68 65 20 73 69 7a 65 20 6f rease the size o
34550 66 20 61 20 42 4c 4f 42 20 75 73 69 6e 67 20 74 f a BLOB using t
34560 68 69 73 20 41 50 49 2e 0a 2a 2a 20 49 66 20 6f his API..** If o
34570 66 66 73 65 74 20 69 4f 66 66 73 65 74 20 69 73 ffset iOffset is
34580 20 6c 65 73 73 20 74 68 61 6e 20 4e 20 62 79 74 less than N byt
34590 65 73 20 66 72 6f 6d 20 74 68 65 20 65 6e 64 20 es from the end
345a0 6f 66 20 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 of the BLOB,.**
345b0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 [SQLITE_ERROR] i
345c0 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e s returned and n
345d0 6f 20 64 61 74 61 20 69 73 20 77 72 69 74 74 65 o data is writte
345e0 6e 2e 20 20 49 66 20 4e 20 69 73 0a 2a 2a 20 6c n. If N is.** l
345f0 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 20 5b 53 ess than zero [S
34600 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 QLITE_ERROR] is
34610 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 returned and no
34620 64 61 74 61 20 69 73 20 77 72 69 74 74 65 6e 2e data is written.
34630 0a 2a 2a 20 54 68 65 20 73 69 7a 65 20 6f 66 20 .** The size of
34640 74 68 65 20 42 4c 4f 42 20 28 61 6e 64 20 68 65 the BLOB (and he
34650 6e 63 65 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 nce the maximum
34660 76 61 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 value of N+iOffs
34670 65 74 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 et).** can be de
34680 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 termined using t
34690 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 he [sqlite3_blob
346a0 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 _bytes()] interf
346b0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 74 ace..**.** An at
346c0 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 74 tempt to write t
346d0 6f 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c o an expired [BL
346e0 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 OB handle] fails
346f0 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f with an.** erro
34700 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 r code of [SQLIT
34710 45 5f 41 42 4f 52 54 5d 2e 20 20 57 72 69 74 65 E_ABORT]. Write
34720 73 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 74 68 s to the BLOB th
34730 61 74 20 6f 63 63 75 72 72 65 64 0a 2a 2a 20 62 at occurred.** b
34740 65 66 6f 72 65 20 74 68 65 20 5b 42 4c 4f 42 20 efore the [BLOB
34750 68 61 6e 64 6c 65 5d 20 65 78 70 69 72 65 64 20 handle] expired
34760 61 72 65 20 6e 6f 74 20 72 6f 6c 6c 65 64 20 62 are not rolled b
34770 61 63 6b 20 62 79 20 74 68 65 0a 2a 2a 20 65 78 ack by the.** ex
34780 70 69 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 piration of the
34790 68 61 6e 64 6c 65 2c 20 74 68 6f 75 67 68 20 6f handle, though o
347a0 66 20 63 6f 75 72 73 65 20 74 68 6f 73 65 20 63 f course those c
347b0 68 61 6e 67 65 73 20 6d 69 67 68 74 0a 2a 2a 20 hanges might.**
347c0 68 61 76 65 20 62 65 65 6e 20 6f 76 65 72 77 72 have been overwr
347d0 69 74 74 65 6e 20 62 79 20 74 68 65 20 73 74 61 itten by the sta
347e0 74 65 6d 65 6e 74 20 74 68 61 74 20 65 78 70 69 tement that expi
347f0 72 65 64 20 74 68 65 20 42 4c 4f 42 20 68 61 6e red the BLOB han
34800 64 6c 65 0a 2a 2a 20 6f 72 20 62 79 20 6f 74 68 dle.** or by oth
34810 65 72 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 73 er independent s
34820 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a tatements..**.**
34830 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 53 51 4c On success, SQL
34840 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e ITE_OK is return
34850 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 ed..** Otherwise
34860 2c 20 61 6e 20 20 5b 65 72 72 6f 72 20 63 6f 64 , an [error cod
34870 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 e] or an [extend
34880 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 ed error code] i
34890 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a s returned..**.*
348a0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f * This routine o
348b0 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b nly works on a [
348c0 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69 BLOB handle] whi
348d0 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 65 61 ch has been crea
348e0 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f ted.** by a prio
348f0 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c r successful cal
34900 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c l to [sqlite3_bl
34910 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77 ob_open()] and w
34920 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 hich has not.**
34930 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b been closed by [
34940 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f sqlite3_blob_clo
34950 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20 se()]. Passing
34960 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65 any other pointe
34970 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20 r in.** to this
34980 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20 routine results
34990 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 in undefined and
349a0 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 probably undesi
349b0 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a rable behavior..
349c0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
349d0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 [sqlite3_blob_re
349e0 61 64 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 ad()]..**.** Req
349f0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
34a00 31 37 38 37 33 5d 20 5b 48 31 37 38 37 34 5d 20 17873] [H17874]
34a10 5b 48 31 37 38 37 35 5d 20 5b 48 31 37 38 37 36 [H17875] [H17876
34a20 5d 20 5b 48 31 37 38 37 37 5d 20 5b 48 31 37 38 ] [H17877] [H178
34a30 37 39 5d 20 5b 48 31 37 38 38 32 5d 20 5b 48 31 79] [H17882] [H1
34a40 37 38 38 35 5d 0a 2a 2a 20 5b 48 31 37 38 38 38 7885].** [H17888
34a50 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
34a60 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 int sqlite3_blob
34a70 5f 77 72 69 74 65 28 73 71 6c 69 74 65 33 5f 62 _write(sqlite3_b
34a80 6c 6f 62 20 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 lob *, const voi
34a90 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 d *z, int n, int
34aa0 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a iOffset);../*.*
34ab0 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 * CAPI3REF: Virt
34ac0 75 61 6c 20 46 69 6c 65 20 53 79 73 74 65 6d 20 ual File System
34ad0 4f 62 6a 65 63 74 73 20 7b 48 31 31 32 30 30 7d Objects {H11200}
34ae0 20 3c 53 32 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S20100>.**.**
34af0 41 20 76 69 72 74 75 61 6c 20 66 69 6c 65 73 79 A virtual filesy
34b00 73 74 65 6d 20 28 56 46 53 29 20 69 73 20 61 6e stem (VFS) is an
34b10 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f [sqlite3_vfs] o
34b20 62 6a 65 63 74 0a 2a 2a 20 74 68 61 74 20 53 51 bject.** that SQ
34b30 4c 69 74 65 20 75 73 65 73 20 74 6f 20 69 6e 74 Lite uses to int
34b40 65 72 61 63 74 0a 2a 2a 20 77 69 74 68 20 74 68 eract.** with th
34b50 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 e underlying ope
34b60 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 rating system.
34b70 4d 6f 73 74 20 53 51 4c 69 74 65 20 62 75 69 6c Most SQLite buil
34b80 64 73 20 63 6f 6d 65 20 77 69 74 68 20 61 0a 2a ds come with a.*
34b90 2a 20 73 69 6e 67 6c 65 20 64 65 66 61 75 6c 74 * single default
34ba0 20 56 46 53 20 74 68 61 74 20 69 73 20 61 70 70 VFS that is app
34bb0 72 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68 65 ropriate for the
34bc0 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a host computer..
34bd0 2a 2a 20 4e 65 77 20 56 46 53 65 73 20 63 61 6e ** New VFSes can
34be0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 61 be registered a
34bf0 6e 64 20 65 78 69 73 74 69 6e 67 20 56 46 53 65 nd existing VFSe
34c00 73 20 63 61 6e 20 62 65 20 75 6e 72 65 67 69 73 s can be unregis
34c10 74 65 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f tered..** The fo
34c20 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 llowing interfac
34c30 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 2e es are provided.
34c40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
34c50 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 20 69 6e e3_vfs_find() in
34c60 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
34c70 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 56 a pointer to a V
34c80 46 53 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d FS given its nam
34c90 65 2e 0a 2a 2a 20 4e 61 6d 65 73 20 61 72 65 20 e..** Names are
34ca0 63 61 73 65 20 73 65 6e 73 69 74 69 76 65 2e 0a case sensitive..
34cb0 2a 2a 20 4e 61 6d 65 73 20 61 72 65 20 7a 65 72 ** Names are zer
34cc0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 o-terminated UTF
34cd0 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 49 -8 strings..** I
34ce0 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 61 f there is no ma
34cf0 74 63 68 2c 20 61 20 4e 55 4c 4c 20 70 6f 69 6e tch, a NULL poin
34d00 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e ter is returned.
34d10 0a 2a 2a 20 49 66 20 7a 56 66 73 4e 61 6d 65 20 .** If zVfsName
34d20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 is NULL then the
34d30 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 default VFS is
34d40 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
34d50 4e 65 77 20 56 46 53 65 73 20 61 72 65 20 72 65 New VFSes are re
34d60 67 69 73 74 65 72 65 64 20 77 69 74 68 20 73 71 gistered with sq
34d70 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 lite3_vfs_regist
34d80 65 72 28 29 2e 0a 2a 2a 20 45 61 63 68 20 6e 65 er()..** Each ne
34d90 77 20 56 46 53 20 62 65 63 6f 6d 65 73 20 74 68 w VFS becomes th
34da0 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 66 e default VFS if
34db0 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c the makeDflt fl
34dc0 61 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20 54 68 ag is set..** Th
34dd0 65 20 73 61 6d 65 20 56 46 53 20 63 61 6e 20 62 e same VFS can b
34de0 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c e registered mul
34df0 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68 tiple times with
34e00 6f 75 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20 54 out injury..** T
34e10 6f 20 6d 61 6b 65 20 61 6e 20 65 78 69 73 74 69 o make an existi
34e20 6e 67 20 56 46 53 20 69 6e 74 6f 20 74 68 65 20 ng VFS into the
34e30 64 65 66 61 75 6c 74 20 56 46 53 2c 20 72 65 67 default VFS, reg
34e40 69 73 74 65 72 20 69 74 20 61 67 61 69 6e 0a 2a ister it again.*
34e50 2a 20 77 69 74 68 20 74 68 65 20 6d 61 6b 65 44 * with the makeD
34e60 66 6c 74 20 66 6c 61 67 20 73 65 74 2e 20 20 49 flt flag set. I
34e70 66 20 74 77 6f 20 64 69 66 66 65 72 65 6e 74 20 f two different
34e80 56 46 53 65 73 20 77 69 74 68 20 74 68 65 0a 2a VFSes with the.*
34e90 2a 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 * same name are
34ea0 72 65 67 69 73 74 65 72 65 64 2c 20 74 68 65 20 registered, the
34eb0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 behavior is unde
34ec0 66 69 6e 65 64 2e 20 20 49 66 20 61 0a 2a 2a 20 fined. If a.**
34ed0 56 46 53 20 69 73 20 72 65 67 69 73 74 65 72 65 VFS is registere
34ee0 64 20 77 69 74 68 20 61 20 6e 61 6d 65 20 74 68 d with a name th
34ef0 61 74 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e at is NULL or an
34f00 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 0a 2a empty string,.*
34f10 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 * then the behav
34f20 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ior is undefined
34f30 2e 0a 2a 2a 0a 2a 2a 20 55 6e 72 65 67 69 73 74 ..**.** Unregist
34f40 65 72 20 61 20 56 46 53 20 77 69 74 68 20 74 68 er a VFS with th
34f50 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e e sqlite3_vfs_un
34f60 72 65 67 69 73 74 65 72 28 29 20 69 6e 74 65 72 register() inter
34f70 66 61 63 65 2e 0a 2a 2a 20 49 66 20 74 68 65 20 face..** If the
34f80 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 75 default VFS is u
34f90 6e 72 65 67 69 73 74 65 72 65 64 2c 20 61 6e 6f nregistered, ano
34fa0 74 68 65 72 20 56 46 53 20 69 73 20 63 68 6f 73 ther VFS is chos
34fb0 65 6e 20 61 73 0a 2a 2a 20 74 68 65 20 64 65 66 en as.** the def
34fc0 61 75 6c 74 2e 20 20 54 68 65 20 63 68 6f 69 63 ault. The choic
34fd0 65 20 66 6f 72 20 74 68 65 20 6e 65 77 20 56 46 e for the new VF
34fe0 53 20 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a S is arbitrary..
34ff0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
35000 74 73 3a 0a 2a 2a 20 5b 48 31 31 32 30 33 5d 20 ts:.** [H11203]
35010 5b 48 31 31 32 30 36 5d 20 5b 48 31 31 32 30 39 [H11206] [H11209
35020 5d 20 5b 48 31 31 32 31 32 5d 20 5b 48 31 31 32 ] [H11212] [H112
35030 31 35 5d 20 5b 48 31 31 32 31 38 5d 0a 2a 2f 0a 15] [H11218].*/.
35040 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 SQLITE_API sqlit
35050 65 33 5f 76 66 73 20 2a 73 71 6c 69 74 65 33 5f e3_vfs *sqlite3_
35060 76 66 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20 63 vfs_find(const c
35070 68 61 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a har *zVfsName);.
35080 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
35090 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 qlite3_vfs_regis
350a0 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ter(sqlite3_vfs*
350b0 2c 20 69 6e 74 20 6d 61 6b 65 44 66 6c 74 29 3b , int makeDflt);
350c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
350d0 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 sqlite3_vfs_unre
350e0 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76 gister(sqlite3_v
350f0 66 73 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 fs*);../*.** CAP
35100 49 33 52 45 46 3a 20 4d 75 74 65 78 65 73 20 7b I3REF: Mutexes {
35110 48 31 37 30 30 30 7d 20 3c 53 32 30 30 30 30 3e H17000} <S20000>
35120 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 .**.** The SQLit
35130 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 e core uses thes
35140 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 74 e routines for t
35150 68 72 65 61 64 0a 2a 2a 20 73 79 6e 63 68 72 6f hread.** synchro
35160 6e 69 7a 61 74 69 6f 6e 2e 20 54 68 6f 75 67 68 nization. Though
35170 20 74 68 65 79 20 61 72 65 20 69 6e 74 65 6e 64 they are intend
35180 65 64 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a ed for internal.
35190 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 ** use by SQLite
351a0 2c 20 63 6f 64 65 20 74 68 61 74 20 6c 69 6e 6b , code that link
351b0 73 20 61 67 61 69 6e 73 74 20 53 51 4c 69 74 65 s against SQLite
351c0 20 69 73 0a 2a 2a 20 70 65 72 6d 69 74 74 65 64 is.** permitted
351d0 20 74 6f 20 75 73 65 20 61 6e 79 20 6f 66 20 74 to use any of t
351e0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a hese routines..*
351f0 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 *.** The SQLite
35200 73 6f 75 72 63 65 20 63 6f 64 65 20 63 6f 6e 74 source code cont
35210 61 69 6e 73 20 6d 75 6c 74 69 70 6c 65 20 69 6d ains multiple im
35220 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a plementations.**
35230 20 6f 66 20 74 68 65 73 65 20 6d 75 74 65 78 20 of these mutex
35240 72 6f 75 74 69 6e 65 73 2e 20 20 41 6e 20 61 70 routines. An ap
35250 70 72 6f 70 72 69 61 74 65 20 69 6d 70 6c 65 6d propriate implem
35260 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 73 entation.** is s
35270 65 6c 65 63 74 65 64 20 61 75 74 6f 6d 61 74 69 elected automati
35280 63 61 6c 6c 79 20 61 74 20 63 6f 6d 70 69 6c 65 cally at compile
35290 2d 74 69 6d 65 2e 20 20 54 68 65 20 66 6f 6c 6c -time. The foll
352a0 6f 77 69 6e 67 0a 2a 2a 20 69 6d 70 6c 65 6d 65 owing.** impleme
352b0 6e 74 61 74 69 6f 6e 73 20 61 72 65 20 61 76 61 ntations are ava
352c0 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 53 51 ilable in the SQ
352d0 4c 69 74 65 20 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a Lite core:.**.**
352e0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20 <ul>.** <li>
352f0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 SQLITE_MUTEX_OS2
35300 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 .** <li> SQLIT
35310 45 5f 4d 55 54 45 58 5f 50 54 48 52 45 41 44 0a E_MUTEX_PTHREAD.
35320 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 ** <li> SQLITE
35330 5f 4d 55 54 45 58 5f 57 33 32 0a 2a 2a 20 3c 6c _MUTEX_W32.** <l
35340 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 i> SQLITE_MUTE
35350 58 5f 4e 4f 4f 50 0a 2a 2a 20 3c 2f 75 6c 3e 0a X_NOOP.** </ul>.
35360 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 **.** The SQLITE
35370 5f 4d 55 54 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c _MUTEX_NOOP impl
35380 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61 20 ementation is a
35390 73 65 74 20 6f 66 20 72 6f 75 74 69 6e 65 73 0a set of routines.
353a0 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 20 ** that does no
353b0 72 65 61 6c 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 real locking and
353c0 20 69 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 is appropriate
353d0 66 6f 72 20 75 73 65 20 69 6e 0a 2a 2a 20 61 20 for use in.** a
353e0 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 20 single-threaded
353f0 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 application. Th
35400 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f e SQLITE_MUTEX_O
35410 53 32 2c 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 S2,.** SQLITE_MU
35420 54 45 58 5f 50 54 48 52 45 41 44 2c 20 61 6e 64 TEX_PTHREAD, and
35430 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 SQLITE_MUTEX_W3
35440 32 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2 implementation
35450 73 0a 2a 2a 20 61 72 65 20 61 70 70 72 6f 70 72 s.** are appropr
35460 69 61 74 65 20 66 6f 72 20 75 73 65 20 6f 6e 20 iate for use on
35470 4f 53 2f 32 2c 20 55 6e 69 78 2c 20 61 6e 64 20 OS/2, Unix, and
35480 57 69 6e 64 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 49 Windows..**.** I
35490 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 f SQLite is comp
354a0 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 iled with the SQ
354b0 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 LITE_MUTEX_APPDE
354c0 46 20 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a F preprocessor.*
354d0 2a 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20 * macro defined
354e0 28 77 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f (with "-DSQLITE_
354f0 4d 55 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29 MUTEX_APPDEF=1")
35500 2c 20 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a , then no mutex.
35510 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
35520 6e 20 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69 n is included wi
35530 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20 th the library.
35540 49 6e 20 74 68 69 73 20 63 61 73 65 20 74 68 65 In this case the
35550 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 .** application
35560 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 63 75 must supply a cu
35570 73 74 6f 6d 20 6d 75 74 65 78 20 69 6d 70 6c 65 stom mutex imple
35580 6d 65 6e 74 61 74 69 6f 6e 20 75 73 69 6e 67 20 mentation using
35590 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 the.** [SQLITE_C
355a0 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 ONFIG_MUTEX] opt
355b0 69 6f 6e 20 6f 66 20 74 68 65 20 73 71 6c 69 74 ion of the sqlit
355c0 65 33 5f 63 6f 6e 66 69 67 28 29 20 66 75 6e 63 e3_config() func
355d0 74 69 6f 6e 0a 2a 2a 20 62 65 66 6f 72 65 20 63 tion.** before c
355e0 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 69 alling sqlite3_i
355f0 6e 69 74 69 61 6c 69 7a 65 28 29 20 6f 72 20 61 nitialize() or a
35600 6e 79 20 6f 74 68 65 72 20 70 75 62 6c 69 63 20 ny other public
35610 73 71 6c 69 74 65 33 5f 0a 2a 2a 20 66 75 6e 63 sqlite3_.** func
35620 74 69 6f 6e 20 74 68 61 74 20 63 61 6c 6c 73 20 tion that calls
35630 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
35640 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 ze()..**.** {H17
35650 30 31 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 011} The sqlite3
35660 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 72 _mutex_alloc() r
35670 6f 75 74 69 6e 65 20 61 6c 6c 6f 63 61 74 65 73 outine allocates
35680 20 61 20 6e 65 77 0a 2a 2a 20 6d 75 74 65 78 20 a new.** mutex
35690 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f and returns a po
356a0 69 6e 74 65 72 20 74 6f 20 69 74 2e 20 7b 48 31 inter to it. {H1
356b0 37 30 31 32 7d 20 49 66 20 69 74 20 72 65 74 75 7012} If it retu
356c0 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74 rns NULL.** that
356d0 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 6d 75 means that a mu
356e0 74 65 78 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 tex could not be
356f0 20 61 6c 6c 6f 63 61 74 65 64 2e 20 7b 48 31 37 allocated. {H17
35700 30 31 33 7d 20 53 51 4c 69 74 65 0a 2a 2a 20 77 013} SQLite.** w
35710 69 6c 6c 20 75 6e 77 69 6e 64 20 69 74 73 20 73 ill unwind its s
35720 74 61 63 6b 20 61 6e 64 20 72 65 74 75 72 6e 20 tack and return
35730 61 6e 20 65 72 72 6f 72 2e 20 7b 48 31 37 30 31 an error. {H1701
35740 34 7d 20 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 4} The argument.
35750 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 ** to sqlite3_mu
35760 74 65 78 5f 61 6c 6c 6f 63 28 29 20 69 73 20 6f tex_alloc() is o
35770 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 ne of these inte
35780 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a ger constants:.*
35790 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
357a0 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f > SQLITE_MUTEX_
357b0 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 FAST.** <li> SQ
357c0 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 LITE_MUTEX_RECUR
357d0 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 SIVE.** <li> SQ
357e0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 LITE_MUTEX_STATI
357f0 43 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c 6c 69 3e C_MASTER.** <li>
35800 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 SQLITE_MUTEX_S
35810 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69 TATIC_MEM.** <li
35820 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f > SQLITE_MUTEX_
35830 53 54 41 54 49 43 5f 4d 45 4d 32 0a 2a 2a 20 3c STATIC_MEM2.** <
35840 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 li> SQLITE_MUTE
35850 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 0a 2a 2a X_STATIC_PRNG.**
35860 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 <li> SQLITE_MU
35870 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 0a 2a TEX_STATIC_LRU.*
35880 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d * <li> SQLITE_M
35890 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 32 UTEX_STATIC_LRU2
358a0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
358b0 7b 48 31 37 30 31 35 7d 20 54 68 65 20 66 69 72 {H17015} The fir
358c0 73 74 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 st two constants
358d0 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 6d cause sqlite3_m
358e0 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20 utex_alloc() to
358f0 63 72 65 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20 create.** a new
35900 6d 75 74 65 78 2e 20 20 54 68 65 20 6e 65 77 20 mutex. The new
35910 6d 75 74 65 78 20 69 73 20 72 65 63 75 72 73 69 mutex is recursi
35920 76 65 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d ve when SQLITE_M
35930 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a UTEX_RECURSIVE.*
35940 2a 20 69 73 20 75 73 65 64 20 62 75 74 20 6e 6f * is used but no
35950 74 20 6e 65 63 65 73 73 61 72 69 6c 79 20 73 6f t necessarily so
35960 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 when SQLITE_MUT
35970 45 58 5f 46 41 53 54 20 69 73 20 75 73 65 64 2e EX_FAST is used.
35980 20 7b 45 4e 44 7d 0a 2a 2a 20 54 68 65 20 6d 75 {END}.** The mu
35990 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 tex implementati
359a0 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 on does not need
359b0 20 74 6f 20 6d 61 6b 65 20 61 20 64 69 73 74 69 to make a disti
359c0 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 nction.** betwee
359d0 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 n SQLITE_MUTEX_R
359e0 45 43 55 52 53 49 56 45 20 61 6e 64 20 53 51 4c ECURSIVE and SQL
359f0 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 69 ITE_MUTEX_FAST i
35a00 66 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 f it does.** not
35a10 20 77 61 6e 74 20 74 6f 2e 20 20 7b 48 31 37 30 want to. {H170
35a20 31 36 7d 20 42 75 74 20 53 51 4c 69 74 65 20 77 16} But SQLite w
35a30 69 6c 6c 20 6f 6e 6c 79 20 72 65 71 75 65 73 74 ill only request
35a40 20 61 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 a recursive mut
35a50 65 78 20 69 6e 0a 2a 2a 20 63 61 73 65 73 20 77 ex in.** cases w
35a60 68 65 72 65 20 69 74 20 72 65 61 6c 6c 79 20 6e here it really n
35a70 65 65 64 73 20 6f 6e 65 2e 20 20 7b 45 4e 44 7d eeds one. {END}
35a80 20 49 66 20 61 20 66 61 73 74 65 72 20 6e 6f 6e If a faster non
35a90 2d 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 -recursive mutex
35aa0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
35ab0 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 on is available
35ac0 6f 6e 20 74 68 65 20 68 6f 73 74 20 70 6c 61 74 on the host plat
35ad0 66 6f 72 6d 2c 20 74 68 65 20 6d 75 74 65 78 20 form, the mutex
35ae0 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20 6d 69 67 subsystem.** mig
35af0 68 74 20 72 65 74 75 72 6e 20 73 75 63 68 20 61 ht return such a
35b00 20 6d 75 74 65 78 20 69 6e 20 72 65 73 70 6f 6e mutex in respon
35b10 73 65 20 74 6f 20 53 51 4c 49 54 45 5f 4d 55 54 se to SQLITE_MUT
35b20 45 58 5f 46 41 53 54 2e 0a 2a 2a 0a 2a 2a 20 7b EX_FAST..**.** {
35b30 48 31 37 30 31 37 7d 20 54 68 65 20 6f 74 68 65 H17017} The othe
35b40 72 20 61 6c 6c 6f 77 65 64 20 70 61 72 61 6d 65 r allowed parame
35b50 74 65 72 73 20 74 6f 20 73 71 6c 69 74 65 33 5f ters to sqlite3_
35b60 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 65 61 mutex_alloc() ea
35b70 63 68 20 72 65 74 75 72 6e 0a 2a 2a 20 61 20 70 ch return.** a p
35b80 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 61 74 ointer to a stat
35b90 69 63 20 70 72 65 65 78 69 73 74 69 6e 67 20 6d ic preexisting m
35ba0 75 74 65 78 2e 20 7b 45 4e 44 7d 20 20 53 69 78 utex. {END} Six
35bb0 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 static mutexes
35bc0 61 72 65 0a 2a 2a 20 75 73 65 64 20 62 79 20 74 are.** used by t
35bd0 68 65 20 63 75 72 72 65 6e 74 20 76 65 72 73 69 he current versi
35be0 6f 6e 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 46 on of SQLite. F
35bf0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f uture versions o
35c00 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 61 79 20 f SQLite.** may
35c10 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 add additional s
35c20 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e 20 20 tatic mutexes.
35c30 53 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 Static mutexes a
35c40 72 65 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a re for internal.
35c50 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 ** use by SQLite
35c60 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 only. Applicat
35c70 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 53 51 ions that use SQ
35c80 4c 69 74 65 20 6d 75 74 65 78 65 73 20 73 68 6f Lite mutexes sho
35c90 75 6c 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79 20 uld.** use only
35ca0 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 the dynamic mute
35cb0 78 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 xes returned by
35cc0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 SQLITE_MUTEX_FAS
35cd0 54 20 6f 72 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d T or.** SQLITE_M
35ce0 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 2e 0a UTEX_RECURSIVE..
35cf0 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 38 7d 20 4e **.** {H17018} N
35d00 6f 74 65 20 74 68 61 74 20 69 66 20 6f 6e 65 20 ote that if one
35d10 6f 66 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d of the dynamic m
35d20 75 74 65 78 20 70 61 72 61 6d 65 74 65 72 73 20 utex parameters
35d30 28 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 (SQLITE_MUTEX_FA
35d40 53 54 0a 2a 2a 20 6f 72 20 53 51 4c 49 54 45 5f ST.** or SQLITE_
35d50 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 29 MUTEX_RECURSIVE)
35d60 20 69 73 20 75 73 65 64 20 74 68 65 6e 20 73 71 is used then sq
35d70 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f lite3_mutex_allo
35d80 63 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 c().** returns a
35d90 20 64 69 66 66 65 72 65 6e 74 20 6d 75 74 65 78 different mutex
35da0 20 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 2e 20 on every call.
35db0 20 7b 48 31 37 30 33 34 7d 20 42 75 74 20 66 6f {H17034} But fo
35dc0 72 20 74 68 65 20 73 74 61 74 69 63 0a 2a 2a 20 r the static.**
35dd0 6d 75 74 65 78 20 74 79 70 65 73 2c 20 74 68 65 mutex types, the
35de0 20 73 61 6d 65 20 6d 75 74 65 78 20 69 73 20 72 same mutex is r
35df0 65 74 75 72 6e 65 64 20 6f 6e 20 65 76 65 72 79 eturned on every
35e00 20 63 61 6c 6c 20 74 68 61 74 20 68 61 73 0a 2a call that has.*
35e10 2a 20 74 68 65 20 73 61 6d 65 20 74 79 70 65 20 * the same type
35e20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 number..**.** {H
35e30 31 37 30 31 39 7d 20 54 68 65 20 73 71 6c 69 74 17019} The sqlit
35e40 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 20 e3_mutex_free()
35e50 72 6f 75 74 69 6e 65 20 64 65 61 6c 6c 6f 63 61 routine dealloca
35e60 74 65 73 20 61 20 70 72 65 76 69 6f 75 73 6c 79 tes a previously
35e70 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 64 79 .** allocated dy
35e80 6e 61 6d 69 63 20 6d 75 74 65 78 2e 20 7b 48 31 namic mutex. {H1
35e90 37 30 32 30 7d 20 53 51 4c 69 74 65 20 69 73 20 7020} SQLite is
35ea0 63 61 72 65 66 75 6c 20 74 6f 20 64 65 61 6c 6c careful to deall
35eb0 6f 63 61 74 65 20 65 76 65 72 79 0a 2a 2a 20 64 ocate every.** d
35ec0 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 74 68 61 ynamic mutex tha
35ed0 74 20 69 74 20 61 6c 6c 6f 63 61 74 65 73 2e 20 t it allocates.
35ee0 7b 41 31 37 30 32 31 7d 20 54 68 65 20 64 79 6e {A17021} The dyn
35ef0 61 6d 69 63 20 6d 75 74 65 78 65 73 20 6d 75 73 amic mutexes mus
35f00 74 20 6e 6f 74 20 62 65 20 69 6e 0a 2a 2a 20 75 t not be in.** u
35f10 73 65 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 se when they are
35f20 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 20 7b 41 deallocated. {A
35f30 31 37 30 32 32 7d 20 41 74 74 65 6d 70 74 69 6e 17022} Attemptin
35f40 67 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 g to deallocate
35f50 61 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 a static.** mute
35f60 78 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 x results in und
35f70 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e efined behavior.
35f80 20 7b 48 31 37 30 32 33 7d 20 53 51 4c 69 74 65 {H17023} SQLite
35f90 20 6e 65 76 65 72 20 64 65 61 6c 6c 6f 63 61 74 never deallocat
35fa0 65 73 0a 2a 2a 20 61 20 73 74 61 74 69 63 20 6d es.** a static m
35fb0 75 74 65 78 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a utex. {END}.**.*
35fc0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 * The sqlite3_mu
35fd0 74 65 78 5f 65 6e 74 65 72 28 29 20 61 6e 64 20 tex_enter() and
35fe0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 sqlite3_mutex_tr
35ff0 79 28 29 20 72 6f 75 74 69 6e 65 73 20 61 74 74 y() routines att
36000 65 6d 70 74 0a 2a 2a 20 74 6f 20 65 6e 74 65 72 empt.** to enter
36010 20 61 20 6d 75 74 65 78 2e 20 7b 48 31 37 30 32 a mutex. {H1702
36020 34 7d 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 4} If another th
36030 72 65 61 64 20 69 73 20 61 6c 72 65 61 64 79 20 read is already
36040 77 69 74 68 69 6e 20 74 68 65 20 6d 75 74 65 78 within the mutex
36050 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 ,.** sqlite3_mut
36060 65 78 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c 20 ex_enter() will
36070 62 6c 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74 65 block and sqlite
36080 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 77 69 3_mutex_try() wi
36090 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c ll return.** SQL
360a0 49 54 45 5f 42 55 53 59 2e 20 7b 48 31 37 30 32 ITE_BUSY. {H1702
360b0 35 7d 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 5} The sqlite3_
360c0 6d 75 74 65 78 5f 74 72 79 28 29 20 69 6e 74 65 mutex_try() inte
360d0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 5b 53 rface returns [S
360e0 51 4c 49 54 45 5f 4f 4b 5d 0a 2a 2a 20 75 70 6f QLITE_OK].** upo
360f0 6e 20 73 75 63 63 65 73 73 66 75 6c 20 65 6e 74 n successful ent
36100 72 79 2e 20 20 7b 48 31 37 30 32 36 7d 20 4d 75 ry. {H17026} Mu
36110 74 65 78 65 73 20 63 72 65 61 74 65 64 20 75 73 texes created us
36120 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 ing.** SQLITE_MU
36130 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 63 61 TEX_RECURSIVE ca
36140 6e 20 62 65 20 65 6e 74 65 72 65 64 20 6d 75 6c n be entered mul
36150 74 69 70 6c 65 20 74 69 6d 65 73 20 62 79 20 74 tiple times by t
36160 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e 0a he same thread..
36170 2a 2a 20 7b 48 31 37 30 32 37 7d 20 49 6e 20 73 ** {H17027} In s
36180 75 63 68 20 63 61 73 65 73 20 74 68 65 2c 0a 2a uch cases the,.*
36190 2a 20 6d 75 74 65 78 20 6d 75 73 74 20 62 65 20 * mutex must be
361a0 65 78 69 74 65 64 20 61 6e 20 65 71 75 61 6c 20 exited an equal
361b0 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 number of times
361c0 62 65 66 6f 72 65 20 61 6e 6f 74 68 65 72 20 74 before another t
361d0 68 72 65 61 64 0a 2a 2a 20 63 61 6e 20 65 6e 74 hread.** can ent
361e0 65 72 2e 20 20 7b 41 31 37 30 32 38 7d 20 49 66 er. {A17028} If
361f0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 the same thread
36200 20 74 72 69 65 73 20 74 6f 20 65 6e 74 65 72 20 tries to enter
36210 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6b 69 6e any other.** kin
36220 64 20 6f 66 20 6d 75 74 65 78 20 6d 6f 72 65 20 d of mutex more
36230 74 68 61 6e 20 6f 6e 63 65 2c 20 74 68 65 20 62 than once, the b
36240 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 ehavior is undef
36250 69 6e 65 64 2e 0a 2a 2a 20 7b 48 31 37 30 32 39 ined..** {H17029
36260 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 } SQLite will ne
36270 76 65 72 20 65 78 68 69 62 69 74 0a 2a 2a 20 73 ver exhibit.** s
36280 75 63 68 20 62 65 68 61 76 69 6f 72 20 69 6e 20 uch behavior in
36290 69 74 73 20 6f 77 6e 20 75 73 65 20 6f 66 20 6d its own use of m
362a0 75 74 65 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 6f utexes..**.** So
362b0 6d 65 20 73 79 73 74 65 6d 73 20 28 66 6f 72 20 me systems (for
362c0 65 78 61 6d 70 6c 65 2c 20 57 69 6e 64 6f 77 73 example, Windows
362d0 20 39 35 29 20 64 6f 20 6e 6f 74 20 73 75 70 70 95) do not supp
362e0 6f 72 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f ort the operatio
362f0 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 65 64 n.** implemented
36300 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 by sqlite3_mute
36310 78 5f 74 72 79 28 29 2e 20 20 4f 6e 20 74 68 6f x_try(). On tho
36320 73 65 20 73 79 73 74 65 6d 73 2c 20 73 71 6c 69 se systems, sqli
36330 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 0a te3_mutex_try().
36340 2a 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 ** will always r
36350 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 42 55 53 eturn SQLITE_BUS
36360 59 2e 20 20 7b 48 31 37 30 33 30 7d 20 54 68 65 Y. {H17030} The
36370 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6f 6e 6c SQLite core onl
36380 79 20 65 76 65 72 20 75 73 65 73 0a 2a 2a 20 73 y ever uses.** s
36390 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 qlite3_mutex_try
363a0 28 29 20 61 73 20 61 6e 20 6f 70 74 69 6d 69 7a () as an optimiz
363b0 61 74 69 6f 6e 20 73 6f 20 74 68 69 73 20 69 73 ation so this is
363c0 20 61 63 63 65 70 74 61 62 6c 65 20 62 65 68 61 acceptable beha
363d0 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 vior..**.** {H17
363e0 30 33 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 031} The sqlite3
363f0 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20 72 _mutex_leave() r
36400 6f 75 74 69 6e 65 20 65 78 69 74 73 20 61 20 6d outine exits a m
36410 75 74 65 78 20 74 68 61 74 20 77 61 73 0a 2a 2a utex that was.**
36420 20 70 72 65 76 69 6f 75 73 6c 79 20 65 6e 74 65 previously ente
36430 72 65 64 20 62 79 20 74 68 65 20 73 61 6d 65 20 red by the same
36440 74 68 72 65 61 64 2e 20 20 7b 41 31 37 30 33 32 thread. {A17032
36450 7d 20 54 68 65 20 62 65 68 61 76 69 6f 72 0a 2a } The behavior.*
36460 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 69 * is undefined i
36470 66 20 74 68 65 20 6d 75 74 65 78 20 69 73 20 6e f the mutex is n
36480 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 ot currently ent
36490 65 72 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 63 ered by the.** c
364a0 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 6f 72 alling thread or
364b0 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c is not currentl
364c0 79 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 7b 48 y allocated. {H
364d0 31 37 30 33 33 7d 20 53 51 4c 69 74 65 20 77 69 17033} SQLite wi
364e0 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 64 6f 20 65 ll.** never do e
364f0 69 74 68 65 72 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a ither. {END}.**.
36500 2a 2a 20 49 66 20 74 68 65 20 61 72 67 75 6d 65 ** If the argume
36510 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 nt to sqlite3_mu
36520 74 65 78 5f 65 6e 74 65 72 28 29 2c 20 73 71 6c tex_enter(), sql
36530 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 ite3_mutex_try()
36540 2c 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f , or.** sqlite3_
36550 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20 69 73 mutex_leave() is
36560 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
36570 20 74 68 65 6e 20 61 6c 6c 20 74 68 72 65 65 20 then all three
36580 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 62 65 68 61 routines.** beha
36590 76 65 20 61 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a ve as no-ops..**
365a0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
365b0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c qlite3_mutex_hel
365c0 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 d()] and [sqlite
365d0 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 3_mutex_notheld(
365e0 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 )]..*/.SQLITE_AP
365f0 49 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 I sqlite3_mutex
36600 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 *sqlite3_mutex_a
36610 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54 lloc(int);.SQLIT
36620 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 E_API void sqlit
36630 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 73 71 e3_mutex_free(sq
36640 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 53 lite3_mutex*);.S
36650 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
36660 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 qlite3_mutex_ent
36670 65 72 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 er(sqlite3_mutex
36680 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 *);.SQLITE_API i
36690 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 nt sqlite3_mutex
366a0 5f 74 72 79 28 73 71 6c 69 74 65 33 5f 6d 75 74 _try(sqlite3_mut
366b0 65 78 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ex*);.SQLITE_API
366c0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 void sqlite3_mu
366d0 74 65 78 5f 6c 65 61 76 65 28 73 71 6c 69 74 65 tex_leave(sqlite
366e0 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 3_mutex*);../*.*
366f0 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 * CAPI3REF: Mute
36700 78 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 x Methods Object
36710 20 7b 48 31 37 31 32 30 7d 20 3c 53 32 30 31 33 {H17120} <S2013
36720 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 0>.** EXPERIMENT
36730 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 AL.**.** An inst
36740 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 ance of this str
36750 75 63 74 75 72 65 20 64 65 66 69 6e 65 73 20 74 ucture defines t
36760 68 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 72 6f 75 he low-level rou
36770 74 69 6e 65 73 0a 2a 2a 20 75 73 65 64 20 74 6f tines.** used to
36780 20 61 6c 6c 6f 63 61 74 65 20 61 6e 64 20 75 73 allocate and us
36790 65 20 6d 75 74 65 78 65 73 2e 0a 2a 2a 0a 2a 2a e mutexes..**.**
367a0 20 55 73 75 61 6c 6c 79 2c 20 74 68 65 20 64 65 Usually, the de
367b0 66 61 75 6c 74 20 6d 75 74 65 78 20 69 6d 70 6c fault mutex impl
367c0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 70 72 6f 76 ementations prov
367d0 69 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 ided by SQLite a
367e0 72 65 0a 2a 2a 20 73 75 66 66 69 63 69 65 6e 74 re.** sufficient
367f0 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 75 73 , however the us
36800 65 72 20 68 61 73 20 74 68 65 20 6f 70 74 69 6f er has the optio
36810 6e 20 6f 66 20 73 75 62 73 74 69 74 75 74 69 6e n of substitutin
36820 67 20 61 20 63 75 73 74 6f 6d 0a 2a 2a 20 69 6d g a custom.** im
36830 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 plementation for
36840 20 73 70 65 63 69 61 6c 69 7a 65 64 20 64 65 70 specialized dep
36850 6c 6f 79 6d 65 6e 74 73 20 6f 72 20 73 79 73 74 loyments or syst
36860 65 6d 73 20 66 6f 72 20 77 68 69 63 68 20 53 51 ems for which SQ
36870 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 Lite.** does not
36880 20 70 72 6f 76 69 64 65 20 61 20 73 75 69 74 61 provide a suita
36890 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ble implementati
368a0 6f 6e 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 on. In this case
368b0 2c 20 74 68 65 20 75 73 65 72 0a 2a 2a 20 63 72 , the user.** cr
368c0 65 61 74 65 73 20 61 6e 64 20 70 6f 70 75 6c 61 eates and popula
368d0 74 65 73 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 tes an instance
368e0 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 of this structur
368f0 65 20 74 6f 20 70 61 73 73 0a 2a 2a 20 74 6f 20 e to pass.** to
36900 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
36910 20 61 6c 6f 6e 67 20 77 69 74 68 20 74 68 65 20 along with the
36920 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
36930 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a 2a 2a UTEX] option..**
36940 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 61 Additionally, a
36950 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
36960 69 73 20 73 74 72 75 63 74 75 72 65 20 63 61 6e is structure can
36970 20 62 65 20 75 73 65 64 20 61 73 20 61 6e 0a 2a be used as an.*
36980 2a 20 6f 75 74 70 75 74 20 76 61 72 69 61 62 6c * output variabl
36990 65 20 77 68 65 6e 20 71 75 65 72 79 69 6e 67 20 e when querying
369a0 74 68 65 20 73 79 73 74 65 6d 20 66 6f 72 20 74 the system for t
369b0 68 65 20 63 75 72 72 65 6e 74 20 6d 75 74 65 78 he current mutex
369c0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
369d0 6f 6e 2c 20 75 73 69 6e 67 20 74 68 65 20 5b 53 on, using the [S
369e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
369f0 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a 2a MUTEX] option..*
36a00 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74 65 78 49 *.** The xMutexI
36a10 6e 69 74 20 6d 65 74 68 6f 64 20 64 65 66 69 6e nit method defin
36a20 65 64 20 62 79 20 74 68 69 73 20 73 74 72 75 63 ed by this struc
36a30 74 75 72 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 ture is invoked
36a40 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 73 79 as.** part of sy
36a50 73 74 65 6d 20 69 6e 69 74 69 61 6c 69 7a 61 74 stem initializat
36a60 69 6f 6e 20 62 79 20 74 68 65 20 73 71 6c 69 74 ion by the sqlit
36a70 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
36a80 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 7b 48 31 function..** {H1
36a90 37 30 30 31 7d 20 54 68 65 20 78 4d 75 74 65 78 7001} The xMutex
36aa0 49 6e 69 74 20 72 6f 75 74 69 6e 65 20 73 68 61 Init routine sha
36ab0 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 79 20 ll be called by
36ac0 53 51 4c 69 74 65 20 6f 6e 63 65 20 66 6f 72 20 SQLite once for
36ad0 65 61 63 68 0a 2a 2a 20 65 66 66 65 63 74 69 76 each.** effectiv
36ae0 65 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 e call to [sqlit
36af0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d e3_initialize()]
36b00 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74 ..**.** The xMut
36b10 65 78 45 6e 64 20 6d 65 74 68 6f 64 20 64 65 66 exEnd method def
36b20 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 74 72 ined by this str
36b30 75 63 74 75 72 65 20 69 73 20 69 6e 76 6f 6b 65 ucture is invoke
36b40 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 d as.** part of
36b50 73 79 73 74 65 6d 20 73 68 75 74 64 6f 77 6e 20 system shutdown
36b60 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 by the sqlite3_s
36b70 68 75 74 64 6f 77 6e 28 29 20 66 75 6e 63 74 69 hutdown() functi
36b80 6f 6e 2e 20 54 68 65 0a 2a 2a 20 69 6d 70 6c 65 on. The.** imple
36b90 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 69 mentation of thi
36ba0 73 20 6d 65 74 68 6f 64 20 69 73 20 65 78 70 65 s method is expe
36bb0 63 74 65 64 20 74 6f 20 72 65 6c 65 61 73 65 20 cted to release
36bc0 61 6c 6c 20 6f 75 74 73 74 61 6e 64 69 6e 67 0a all outstanding.
36bd0 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 6f 62 74 ** resources obt
36be0 61 69 6e 65 64 20 62 79 20 74 68 65 20 6d 75 74 ained by the mut
36bf0 65 78 20 6d 65 74 68 6f 64 73 20 69 6d 70 6c 65 ex methods imple
36c00 6d 65 6e 74 61 74 69 6f 6e 2c 20 65 73 70 65 63 mentation, espec
36c10 69 61 6c 6c 79 0a 2a 2a 20 74 68 6f 73 65 20 6f ially.** those o
36c20 62 74 61 69 6e 65 64 20 62 79 20 74 68 65 20 78 btained by the x
36c30 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 MutexInit method
36c40 2e 20 7b 48 31 37 30 30 33 7d 20 54 68 65 20 78 . {H17003} The x
36c50 4d 75 74 65 78 45 6e 64 28 29 0a 2a 2a 20 69 6e MutexEnd().** in
36c60 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 62 65 terface shall be
36c70 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f invoked once fo
36c80 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b r each call to [
36c90 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
36ca0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 ()]..**.** The r
36cb0 65 6d 61 69 6e 69 6e 67 20 73 65 76 65 6e 20 6d emaining seven m
36cc0 65 74 68 6f 64 73 20 64 65 66 69 6e 65 64 20 62 ethods defined b
36cd0 79 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 y this structure
36ce0 20 28 78 4d 75 74 65 78 41 6c 6c 6f 63 2c 0a 2a (xMutexAlloc,.*
36cf0 2a 20 78 4d 75 74 65 78 46 72 65 65 2c 20 78 4d * xMutexFree, xM
36d00 75 74 65 78 45 6e 74 65 72 2c 20 78 4d 75 74 65 utexEnter, xMute
36d10 78 54 72 79 2c 20 78 4d 75 74 65 78 4c 65 61 76 xTry, xMutexLeav
36d20 65 2c 20 78 4d 75 74 65 78 48 65 6c 64 20 61 6e e, xMutexHeld an
36d30 64 0a 2a 2a 20 78 4d 75 74 65 78 4e 6f 74 68 65 d.** xMutexNothe
36d40 6c 64 29 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 ld) implement th
36d50 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 e following inte
36d60 72 66 61 63 65 73 20 28 72 65 73 70 65 63 74 69 rfaces (respecti
36d70 76 65 6c 79 29 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c vely):.**.** <ul
36d80 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 >.** <li> [sq
36d90 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f lite3_mutex_allo
36da0 63 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 c()] </li>.**
36db0 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d <li> [sqlite3_m
36dc0 75 74 65 78 5f 66 72 65 65 28 29 5d 20 3c 2f 6c utex_free()] </l
36dd0 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 i>.** <li> [s
36de0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 qlite3_mutex_ent
36df0 65 72 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 er()] </li>.**
36e00 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f <li> [sqlite3_
36e10 6d 75 74 65 78 5f 74 72 79 28 29 5d 20 3c 2f 6c mutex_try()] </l
36e20 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 i>.** <li> [s
36e30 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 qlite3_mutex_lea
36e40 76 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 ve()] </li>.**
36e50 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f <li> [sqlite3_
36e60 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 3c 2f mutex_held()] </
36e70 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b li>.** <li> [
36e80 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f sqlite3_mutex_no
36e90 74 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a theld()] </li>.*
36ea0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 * </ul>.**.** Th
36eb0 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 e only differenc
36ec0 65 20 69 73 20 74 68 61 74 20 74 68 65 20 70 75 e is that the pu
36ed0 62 6c 69 63 20 73 71 6c 69 74 65 33 5f 58 58 58 blic sqlite3_XXX
36ee0 20 66 75 6e 63 74 69 6f 6e 73 20 65 6e 75 6d 65 functions enume
36ef0 72 61 74 65 64 0a 2a 2a 20 61 62 6f 76 65 20 73 rated.** above s
36f00 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 61 ilently ignore a
36f10 6e 79 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 74 ny invocations t
36f20 68 61 74 20 70 61 73 73 20 61 20 4e 55 4c 4c 20 hat pass a NULL
36f30 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 0a pointer instead.
36f40 2a 2a 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 ** of a valid mu
36f50 74 65 78 20 68 61 6e 64 6c 65 2e 20 54 68 65 20 tex handle. The
36f60 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
36f70 6f 66 20 74 68 65 20 6d 65 74 68 6f 64 73 20 64 of the methods d
36f80 65 66 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69 efined.** by thi
36f90 73 20 73 74 72 75 63 74 75 72 65 20 61 72 65 20 s structure are
36fa0 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 not required to
36fb0 68 61 6e 64 6c 65 20 74 68 69 73 20 63 61 73 65 handle this case
36fc0 2c 20 74 68 65 20 72 65 73 75 6c 74 73 0a 2a 2a , the results.**
36fd0 20 6f 66 20 70 61 73 73 69 6e 67 20 61 20 4e 55 of passing a NU
36fe0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 LL pointer inste
36ff0 61 64 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 ad of a valid mu
37000 74 65 78 20 68 61 6e 64 6c 65 20 61 72 65 20 75 tex handle are u
37010 6e 64 65 66 69 6e 65 64 0a 2a 2a 20 28 69 2e 65 ndefined.** (i.e
37020 2e 20 69 74 20 69 73 20 61 63 63 65 70 74 61 62 . it is acceptab
37030 6c 65 20 74 6f 20 70 72 6f 76 69 64 65 20 61 6e le to provide an
37040 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
37050 74 68 61 74 20 73 65 67 66 61 75 6c 74 73 20 69 that segfaults i
37060 66 0a 2a 2a 20 69 74 20 69 73 20 70 61 73 73 65 f.** it is passe
37070 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 d a NULL pointer
37080 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 )..**.** The xMu
37090 74 65 78 49 6e 69 74 28 29 20 6d 65 74 68 6f 64 texInit() method
370a0 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 must be threads
370b0 61 66 65 2e 20 20 49 74 20 6d 75 73 74 20 62 65 afe. It must be
370c0 20 68 61 72 6d 6c 65 73 73 20 74 6f 0a 2a 2a 20 harmless to.**
370d0 69 6e 76 6f 6b 65 20 78 4d 75 74 65 78 49 6e 69 invoke xMutexIni
370e0 74 28 29 20 6d 75 74 69 70 6c 65 20 74 69 6d 65 t() mutiple time
370f0 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d s within the sam
37100 65 20 70 72 6f 63 65 73 73 20 61 6e 64 20 77 69 e process and wi
37110 74 68 6f 75 74 0a 2a 2a 20 69 6e 74 65 72 76 65 thout.** interve
37120 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 78 4d ning calls to xM
37130 75 74 65 78 45 6e 64 28 29 2e 20 20 53 65 63 6f utexEnd(). Seco
37140 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e nd and subsequen
37150 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 78 4d t calls to.** xM
37160 75 74 65 78 49 6e 69 74 28 29 20 6d 75 73 74 20 utexInit() must
37170 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a be no-ops..**.**
37180 20 78 4d 75 74 65 78 49 6e 69 74 28 29 20 6d 75 xMutexInit() mu
37190 73 74 20 6e 6f 74 20 75 73 65 20 53 51 4c 69 74 st not use SQLit
371a0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
371b0 69 6f 6e 20 28 5b 73 71 6c 69 74 65 33 5f 6d 61 ion ([sqlite3_ma
371c0 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 61 6e 64 20 69 lloc()].** and i
371d0 74 73 20 61 73 73 6f 63 69 61 74 65 73 29 2e 20 ts associates).
371e0 20 53 69 6d 69 6c 61 72 6c 79 2c 20 78 4d 75 74 Similarly, xMut
371f0 65 78 41 6c 6c 6f 63 28 29 20 6d 75 73 74 20 6e exAlloc() must n
37200 6f 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d 65 ot use SQLite me
37210 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 mory.** allocati
37220 6f 6e 20 66 6f 72 20 61 20 73 74 61 74 69 63 20 on for a static
37230 6d 75 74 65 78 2e 20 20 48 6f 77 65 76 65 72 20 mutex. However
37240 78 4d 75 74 65 78 41 6c 6c 6f 63 28 29 20 6d 61 xMutexAlloc() ma
37250 79 20 75 73 65 20 53 51 4c 69 74 65 0a 2a 2a 20 y use SQLite.**
37260 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
37270 6e 20 66 6f 72 20 61 20 66 61 73 74 20 6f 72 20 n for a fast or
37280 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 2e recursive mutex.
37290 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 .**.** SQLite wi
372a0 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 78 4d ll invoke the xM
372b0 75 74 65 78 45 6e 64 28 29 20 6d 65 74 68 6f 64 utexEnd() method
372c0 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 when [sqlite3_s
372d0 68 75 74 64 6f 77 6e 28 29 5d 20 69 73 0a 2a 2a hutdown()] is.**
372e0 20 63 61 6c 6c 65 64 2c 20 62 75 74 20 6f 6e 6c called, but onl
372f0 79 20 69 66 20 74 68 65 20 70 72 69 6f 72 20 63 y if the prior c
37300 61 6c 6c 20 74 6f 20 78 4d 75 74 65 78 49 6e 69 all to xMutexIni
37310 74 20 72 65 74 75 72 6e 65 64 20 53 51 4c 49 54 t returned SQLIT
37320 45 5f 4f 4b 2e 0a 2a 2a 20 49 66 20 78 4d 75 74 E_OK..** If xMut
37330 65 78 49 6e 69 74 20 66 61 69 6c 73 20 69 6e 20 exInit fails in
37340 61 6e 79 20 77 61 79 2c 20 69 74 20 69 73 20 65 any way, it is e
37350 78 70 65 63 74 65 64 20 74 6f 20 63 6c 65 61 6e xpected to clean
37360 20 75 70 20 61 66 74 65 72 20 69 74 73 65 6c 66 up after itself
37370 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 72 65 74 .** prior to ret
37380 75 72 6e 69 6e 67 2e 0a 2a 2f 0a 74 79 70 65 64 urning..*/.typed
37390 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
373a0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 20 3_mutex_methods
373b0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 sqlite3_mutex_me
373c0 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 thods;.struct sq
373d0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 lite3_mutex_meth
373e0 6f 64 73 20 7b 0a 20 20 69 6e 74 20 28 2a 78 4d ods {. int (*xM
373f0 75 74 65 78 49 6e 69 74 29 28 76 6f 69 64 29 3b utexInit)(void);
37400 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 45 . int (*xMutexE
37410 6e 64 29 28 76 6f 69 64 29 3b 0a 20 20 73 71 6c nd)(void);. sql
37420 69 74 65 33 5f 6d 75 74 65 78 20 2a 28 2a 78 4d ite3_mutex *(*xM
37430 75 74 65 78 41 6c 6c 6f 63 29 28 69 6e 74 29 3b utexAlloc)(int);
37440 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 74 65 78 . void (*xMutex
37450 46 72 65 65 29 28 73 71 6c 69 74 65 33 5f 6d 75 Free)(sqlite3_mu
37460 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28 tex *);. void (
37470 2a 78 4d 75 74 65 78 45 6e 74 65 72 29 28 73 71 *xMutexEnter)(sq
37480 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a lite3_mutex *);.
37490 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 54 72 int (*xMutexTr
374a0 79 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 y)(sqlite3_mutex
374b0 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d *);. void (*xM
374c0 75 74 65 78 4c 65 61 76 65 29 28 73 71 6c 69 74 utexLeave)(sqlit
374d0 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 69 e3_mutex *);. i
374e0 6e 74 20 28 2a 78 4d 75 74 65 78 48 65 6c 64 29 nt (*xMutexHeld)
374f0 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a (sqlite3_mutex *
37500 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 );. int (*xMute
37510 78 4e 6f 74 68 65 6c 64 29 28 73 71 6c 69 74 65 xNotheld)(sqlite
37520 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 7d 3b 0a 0a 3_mutex *);.};..
37530 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
37540 4d 75 74 65 78 20 56 65 72 69 66 69 63 61 74 69 Mutex Verificati
37550 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b 48 31 37 on Routines {H17
37560 30 38 30 7d 20 3c 53 32 30 31 33 30 3e 20 3c 53 080} <S20130> <S
37570 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 30800>.**.** The
37580 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 sqlite3_mutex_h
37590 65 6c 64 28 29 20 61 6e 64 20 73 71 6c 69 74 65 eld() and sqlite
375a0 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 3_mutex_notheld(
375b0 29 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 ) routines.** ar
375c0 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 e intended for u
375d0 73 65 20 69 6e 73 69 64 65 20 61 73 73 65 72 74 se inside assert
375e0 28 29 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 7b () statements. {
375f0 48 31 37 30 38 31 7d 20 54 68 65 20 53 51 4c 69 H17081} The SQLi
37600 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 65 72 te core.** never
37610 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 uses these rout
37620 69 6e 65 73 20 65 78 63 65 70 74 20 69 6e 73 69 ines except insi
37630 64 65 20 61 6e 20 61 73 73 65 72 74 28 29 20 61 de an assert() a
37640 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a nd applications.
37650 2a 2a 20 61 72 65 20 61 64 76 69 73 65 64 20 74 ** are advised t
37660 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c 65 61 o follow the lea
37670 64 20 6f 66 20 74 68 65 20 63 6f 72 65 2e 20 20 d of the core.
37680 7b 48 31 37 30 38 32 7d 20 54 68 65 20 63 6f 72 {H17082} The cor
37690 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69 64 e only.** provid
376a0 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f es implementatio
376b0 6e 73 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 ns for these rou
376c0 74 69 6e 65 73 20 77 68 65 6e 20 69 74 20 69 73 tines when it is
376d0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 compiled.** wit
376e0 68 20 74 68 65 20 53 51 4c 49 54 45 5f 44 45 42 h the SQLITE_DEB
376f0 55 47 20 66 6c 61 67 2e 20 20 7b 41 31 37 30 38 UG flag. {A1708
37700 37 7d 20 45 78 74 65 72 6e 61 6c 20 6d 75 74 65 7} External mute
37710 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e x implementation
37720 73 0a 2a 2a 20 61 72 65 20 6f 6e 6c 79 20 72 65 s.** are only re
37730 71 75 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64 quired to provid
37740 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 e these routines
37750 20 69 66 20 53 51 4c 49 54 45 5f 44 45 42 55 47 if SQLITE_DEBUG
37760 20 69 73 0a 2a 2a 20 64 65 66 69 6e 65 64 20 61 is.** defined a
37770 6e 64 20 69 66 20 4e 44 45 42 55 47 20 69 73 20 nd if NDEBUG is
37780 6e 6f 74 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a not defined..**.
37790 2a 2a 20 7b 48 31 37 30 38 33 7d 20 54 68 65 73 ** {H17083} Thes
377a0 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c e routines shoul
377b0 64 20 72 65 74 75 72 6e 20 74 72 75 65 20 69 66 d return true if
377c0 20 74 68 65 20 6d 75 74 65 78 20 69 6e 20 74 68 the mutex in th
377d0 65 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 eir argument.**
377e0 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20 68 is held or not h
377f0 65 6c 64 2c 20 72 65 73 70 65 63 74 69 76 65 6c eld, respectivel
37800 79 2c 20 62 79 20 74 68 65 20 63 61 6c 6c 69 6e y, by the callin
37810 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 g thread..**.**
37820 7b 58 31 37 30 38 34 7d 20 54 68 65 20 69 6d 70 {X17084} The imp
37830 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e lementation is n
37840 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 70 ot required to p
37850 72 6f 76 69 64 65 64 20 76 65 72 73 69 6f 6e 73 rovided versions
37860 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 72 6f 75 of these.** rou
37870 74 69 6e 65 73 20 74 68 61 74 20 61 63 74 75 61 tines that actua
37880 6c 6c 79 20 77 6f 72 6b 2e 20 49 66 20 74 68 65 lly work. If the
37890 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
378a0 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 does not provide
378b0 20 77 6f 72 6b 69 6e 67 0a 2a 2a 20 76 65 72 73 working.** vers
378c0 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 20 72 6f ions of these ro
378d0 75 74 69 6e 65 73 2c 20 69 74 20 73 68 6f 75 6c utines, it shoul
378e0 64 20 61 74 20 6c 65 61 73 74 20 70 72 6f 76 69 d at least provi
378f0 64 65 20 73 74 75 62 73 20 74 68 61 74 20 61 6c de stubs that al
37900 77 61 79 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74 ways.** return t
37910 72 75 65 20 73 6f 20 74 68 61 74 20 6f 6e 65 20 rue so that one
37920 64 6f 65 73 20 6e 6f 74 20 67 65 74 20 73 70 75 does not get spu
37930 72 69 6f 75 73 20 61 73 73 65 72 74 69 6f 6e 20 rious assertion
37940 66 61 69 6c 75 72 65 73 2e 0a 2a 2a 0a 2a 2a 20 failures..**.**
37950 7b 48 31 37 30 38 35 7d 20 49 66 20 74 68 65 20 {H17085} If the
37960 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
37970 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 te3_mutex_held()
37980 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
37990 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 er then.** the r
379a0 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 72 65 outine should re
379b0 74 75 72 6e 20 31 2e 20 20 7b 45 4e 44 7d 20 54 turn 1. {END} T
379c0 68 69 73 20 73 65 65 6d 73 20 63 6f 75 6e 74 65 his seems counte
379d0 72 2d 69 6e 74 75 69 74 69 76 65 20 73 69 6e 63 r-intuitive sinc
379e0 65 0a 2a 2a 20 63 6c 65 61 72 6c 79 20 74 68 65 e.** clearly the
379f0 20 6d 75 74 65 78 20 63 61 6e 6e 6f 74 20 62 65 mutex cannot be
37a00 20 68 65 6c 64 20 69 66 20 69 74 20 64 6f 65 73 held if it does
37a10 20 6e 6f 74 20 65 78 69 73 74 2e 20 20 42 75 74 not exist. But
37a20 20 74 68 65 0a 2a 2a 20 74 68 65 20 72 65 61 73 the.** the reas
37a30 6f 6e 20 74 68 65 20 6d 75 74 65 78 20 64 6f 65 on the mutex doe
37a40 73 20 6e 6f 74 20 65 78 69 73 74 20 69 73 20 62 s not exist is b
37a50 65 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 64 ecause the build
37a60 20 69 73 20 6e 6f 74 0a 2a 2a 20 75 73 69 6e 67 is not.** using
37a70 20 6d 75 74 65 78 65 73 2e 20 20 41 6e 64 20 77 mutexes. And w
37a80 65 20 64 6f 20 6e 6f 74 20 77 61 6e 74 20 74 68 e do not want th
37a90 65 20 61 73 73 65 72 74 28 29 20 63 6f 6e 74 61 e assert() conta
37aa0 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 61 6c ining the.** cal
37ab0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 l to sqlite3_mut
37ac0 65 78 5f 68 65 6c 64 28 29 20 74 6f 20 66 61 69 ex_held() to fai
37ad0 6c 2c 20 73 6f 20 61 20 6e 6f 6e 2d 7a 65 72 6f l, so a non-zero
37ae0 20 72 65 74 75 72 6e 20 69 73 0a 2a 2a 20 74 68 return is.** th
37af0 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 74 68 e appropriate th
37b00 69 6e 67 20 74 6f 20 64 6f 2e 20 20 7b 48 31 37 ing to do. {H17
37b10 30 38 36 7d 20 54 68 65 20 73 71 6c 69 74 65 33 086} The sqlite3
37b20 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 _mutex_notheld()
37b30 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 73 68 .** interface sh
37b40 6f 75 6c 64 20 61 6c 73 6f 20 72 65 74 75 72 6e ould also return
37b50 20 31 20 77 68 65 6e 20 67 69 76 65 6e 20 61 20 1 when given a
37b60 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f NULL pointer..*/
37b70 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
37b80 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 sqlite3_mutex_he
37b90 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 ld(sqlite3_mutex
37ba0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 *);.SQLITE_API i
37bb0 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 nt sqlite3_mutex
37bc0 5f 6e 6f 74 68 65 6c 64 28 73 71 6c 69 74 65 33 _notheld(sqlite3
37bd0 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a _mutex*);../*.**
37be0 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 CAPI3REF: Mutex
37bf0 20 54 79 70 65 73 20 7b 48 31 37 30 30 31 7d 20 Types {H17001}
37c00 3c 48 31 37 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <H17000>.**.** T
37c10 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 he [sqlite3_mute
37c20 78 5f 61 6c 6c 6f 63 28 29 5d 20 69 6e 74 65 72 x_alloc()] inter
37c30 66 61 63 65 20 74 61 6b 65 73 20 61 20 73 69 6e face takes a sin
37c40 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 gle argument.**
37c50 77 68 69 63 68 20 69 73 20 6f 6e 65 20 6f 66 20 which is one of
37c60 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f these integer co
37c70 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 nstants..**.** T
37c80 68 65 20 73 65 74 20 6f 66 20 73 74 61 74 69 63 he set of static
37c90 20 6d 75 74 65 78 65 73 20 6d 61 79 20 63 68 61 mutexes may cha
37ca0 6e 67 65 20 66 72 6f 6d 20 6f 6e 65 20 53 51 4c nge from one SQL
37cb0 69 74 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 ite release to t
37cc0 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 he.** next. App
37cd0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6f lications that o
37ce0 76 65 72 72 69 64 65 20 74 68 65 20 62 75 69 6c verride the buil
37cf0 74 2d 69 6e 20 6d 75 74 65 78 20 6c 6f 67 69 63 t-in mutex logic
37d00 20 6d 75 73 74 20 62 65 0a 2a 2a 20 70 72 65 70 must be.** prep
37d10 61 72 65 64 20 74 6f 20 61 63 63 6f 6d 6d 6f 64 ared to accommod
37d20 61 74 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 ate additional s
37d30 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e 0a 2a tatic mutexes..*
37d40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
37d50 5f 4d 55 54 45 58 5f 46 41 53 54 20 20 20 20 20 _MUTEX_FAST
37d60 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 0.#defin
37d70 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 e SQLITE_MUTEX_R
37d80 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20 20 ECURSIVE
37d90 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
37da0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 _MUTEX_STATIC_MA
37db0 53 54 45 52 20 20 20 20 32 0a 23 64 65 66 69 6e STER 2.#defin
37dc0 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 e SQLITE_MUTEX_S
37dd0 54 41 54 49 43 5f 4d 45 4d 20 20 20 20 20 20 20 TATIC_MEM
37de0 33 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 61 3 /* sqlite3_ma
37df0 6c 6c 6f 63 28 29 20 2a 2f 0a 23 64 65 66 69 6e lloc() */.#defin
37e00 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 e SQLITE_MUTEX_S
37e10 54 41 54 49 43 5f 4d 45 4d 32 20 20 20 20 20 20 TATIC_MEM2
37e20 34 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 20 2a 4 /* NOT USED *
37e30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
37e40 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4f 50 _MUTEX_STATIC_OP
37e50 45 4e 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 EN 4 /* sq
37e60 6c 69 74 65 33 42 74 72 65 65 4f 70 65 6e 28 29 lite3BtreeOpen()
37e70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
37e80 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
37e90 50 52 4e 47 20 20 20 20 20 20 35 20 20 2f 2a 20 PRNG 5 /*
37ea0 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 28 29 sqlite3_random()
37eb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
37ec0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
37ed0 4c 52 55 20 20 20 20 20 20 20 36 20 20 2f 2a 20 LRU 6 /*
37ee0 6c 72 75 20 70 61 67 65 20 6c 69 73 74 20 2a 2f lru page list */
37ef0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
37f00 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 MUTEX_STATIC_LRU
37f10 32 20 20 20 20 20 20 37 20 20 2f 2a 20 6c 72 75 2 7 /* lru
37f20 20 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a 0a 2f page list */../
37f30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
37f40 65 74 72 69 65 76 65 20 74 68 65 20 6d 75 74 65 etrieve the mute
37f50 78 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 x for a database
37f60 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 37 connection {H17
37f70 30 30 32 7d 20 3c 48 31 37 30 30 30 3e 0a 2a 2a 002} <H17000>.**
37f80 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 .** This interfa
37f90 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 ce returns a poi
37fa0 6e 74 65 72 20 74 68 65 20 5b 73 71 6c 69 74 65 nter the [sqlite
37fb0 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 20 3_mutex] object
37fc0 74 68 61 74 20 0a 2a 2a 20 73 65 72 69 61 6c 69 that .** seriali
37fd0 7a 65 73 20 61 63 63 65 73 73 20 74 6f 20 74 68 zes access to th
37fe0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
37ff0 65 63 74 69 6f 6e 5d 20 67 69 76 65 6e 20 69 6e ection] given in
38000 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a the argument.**
38010 20 77 68 65 6e 20 74 68 65 20 5b 74 68 72 65 61 when the [threa
38020 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 53 65 ding mode] is Se
38030 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 49 66 20 rialized..** If
38040 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d the [threading m
38050 6f 64 65 5d 20 69 73 20 53 69 6e 67 6c 65 2d 74 ode] is Single-t
38060 68 72 65 61 64 20 6f 72 20 4d 75 6c 74 69 2d 74 hread or Multi-t
38070 68 72 65 61 64 20 74 68 65 6e 20 74 68 69 73 0a hread then this.
38080 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 ** routine retur
38090 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ns a NULL pointe
380a0 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 r..*/.SQLITE_API
380b0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a sqlite3_mutex *
380c0 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 sqlite3_db_mutex
380d0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
380e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 77 ** CAPI3REF: Low
380f0 2d 4c 65 76 65 6c 20 43 6f 6e 74 72 6f 6c 20 4f -Level Control O
38100 66 20 44 61 74 61 62 61 73 65 20 46 69 6c 65 73 f Database Files
38110 20 7b 48 31 31 33 30 30 7d 20 3c 53 33 30 38 30 {H11300} <S3080
38120 30 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 31 0>.**.** {H11301
38130 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 } The [sqlite3_f
38140 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 ile_control()] i
38150 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 nterface makes a
38160 20 64 69 72 65 63 74 20 63 61 6c 6c 20 74 6f 20 direct call to
38170 74 68 65 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 the.** xFileCont
38180 72 6f 6c 20 6d 65 74 68 6f 64 20 66 6f 72 20 74 rol method for t
38190 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d he [sqlite3_io_m
381a0 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 ethods] object a
381b0 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 ssociated.** wit
381c0 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 h a particular d
381d0 61 74 61 62 61 73 65 20 69 64 65 6e 74 69 66 69 atabase identifi
381e0 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 ed by the second
381f0 20 61 72 67 75 6d 65 6e 74 2e 20 7b 48 31 31 33 argument. {H113
38200 30 32 7d 20 54 68 65 0a 2a 2a 20 6e 61 6d 65 20 02} The.** name
38210 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 of the database
38220 69 73 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 is the name assi
38230 67 6e 65 64 20 74 6f 20 74 68 65 20 64 61 74 61 gned to the data
38240 62 61 73 65 20 62 79 20 74 68 65 0a 2a 2a 20 3c base by the.** <
38250 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f 61 74 74 a href="lang_att
38260 61 63 68 2e 68 74 6d 6c 22 3e 41 54 54 41 43 48 ach.html">ATTACH
38270 3c 2f 61 3e 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 </a> SQL command
38280 20 74 68 61 74 20 6f 70 65 6e 65 64 20 74 68 65 that opened the
38290 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 7b 48 .** database. {H
382a0 31 31 33 30 33 7d 20 54 6f 20 63 6f 6e 74 72 6f 11303} To contro
382b0 6c 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 l the main datab
382c0 61 73 65 20 66 69 6c 65 2c 20 75 73 65 20 74 68 ase file, use th
382d0 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 0a 2a 2a e name "main".**
382e0 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 or a NULL point
382f0 65 72 2e 20 7b 48 31 31 33 30 34 7d 20 54 68 65 er. {H11304} The
38300 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 third and fourt
38310 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 h parameters to
38320 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 this routine.**
38330 61 72 65 20 70 61 73 73 65 64 20 64 69 72 65 63 are passed direc
38340 74 6c 79 20 74 68 72 6f 75 67 68 20 74 6f 20 74 tly through to t
38350 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 he second and th
38360 69 72 64 20 70 61 72 61 6d 65 74 65 72 73 20 6f ird parameters o
38370 66 0a 2a 2a 20 74 68 65 20 78 46 69 6c 65 43 6f f.** the xFileCo
38380 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 20 7b ntrol method. {
38390 48 31 31 33 30 35 7d 20 54 68 65 20 72 65 74 75 H11305} The retu
383a0 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 rn value of the
383b0 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 0a 2a 2a 20 xFileControl.**
383c0 6d 65 74 68 6f 64 20 62 65 63 6f 6d 65 73 20 74 method becomes t
383d0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
383e0 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e of this routine.
383f0 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 36 7d 20 .**.** {H11306}
38400 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 If the second pa
38410 72 61 6d 65 74 65 72 20 28 7a 44 62 4e 61 6d 65 rameter (zDbName
38420 29 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 ) does not match
38430 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 6e 79 the name of any
38440 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61 62 61 73 .** open databas
38450 65 20 66 69 6c 65 2c 20 74 68 65 6e 20 53 51 4c e file, then SQL
38460 49 54 45 5f 45 52 52 4f 52 20 69 73 20 72 65 74 ITE_ERROR is ret
38470 75 72 6e 65 64 2e 20 7b 48 31 31 33 30 37 7d 20 urned. {H11307}
38480 54 68 69 73 20 65 72 72 6f 72 0a 2a 2a 20 63 6f This error.** co
38490 64 65 20 69 73 20 6e 6f 74 20 72 65 6d 65 6d 62 de is not rememb
384a0 65 72 65 64 20 61 6e 64 20 77 69 6c 6c 20 6e 6f ered and will no
384b0 74 20 62 65 20 72 65 63 61 6c 6c 65 64 20 62 79 t be recalled by
384c0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 [sqlite3_errcod
384d0 65 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 e()].** or [sqli
384e0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 20 7b te3_errmsg()]. {
384f0 41 31 31 33 30 38 7d 20 54 68 65 20 75 6e 64 65 A11308} The unde
38500 72 6c 79 69 6e 67 20 78 46 69 6c 65 43 6f 6e 74 rlying xFileCont
38510 72 6f 6c 20 6d 65 74 68 6f 64 20 6d 69 67 68 74 rol method might
38520 0a 2a 2a 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 .** also return
38530 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 7b SQLITE_ERROR. {
38540 41 31 31 33 30 39 7d 20 54 68 65 72 65 20 69 73 A11309} There is
38550 20 6e 6f 20 77 61 79 20 74 6f 20 64 69 73 74 69 no way to disti
38560 6e 67 75 69 73 68 20 62 65 74 77 65 65 6e 0a 2a nguish between.*
38570 2a 20 61 6e 20 69 6e 63 6f 72 72 65 63 74 20 7a * an incorrect z
38580 44 62 4e 61 6d 65 20 61 6e 64 20 61 6e 20 53 51 DbName and an SQ
38590 4c 49 54 45 5f 45 52 52 4f 52 20 72 65 74 75 72 LITE_ERROR retur
385a0 6e 20 66 72 6f 6d 20 74 68 65 20 75 6e 64 65 72 n from the under
385b0 6c 79 69 6e 67 0a 2a 2a 20 78 46 69 6c 65 43 6f lying.** xFileCo
385c0 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 7b 45 ntrol method. {E
385d0 4e 44 7d 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c ND}.**.** See al
385e0 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 so: [SQLITE_FCNT
385f0 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 0a 2a 2f 0a L_LOCKSTATE].*/.
38600 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
38610 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
38620 72 6f 6c 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f rol(sqlite3*, co
38630 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d nst char *zDbNam
38640 65 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 2a e, int op, void*
38650 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
38660 45 46 3a 20 54 65 73 74 69 6e 67 20 49 6e 74 65 EF: Testing Inte
38670 72 66 61 63 65 20 7b 48 31 31 34 30 30 7d 20 3c rface {H11400} <
38680 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S30800>.**.** Th
38690 65 20 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 e sqlite3_test_c
386a0 6f 6e 74 72 6f 6c 28 29 20 69 6e 74 65 72 66 61 ontrol() interfa
386b0 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 ce is used to re
386c0 61 64 20 6f 75 74 20 69 6e 74 65 72 6e 61 6c 0a ad out internal.
386d0 2a 2a 20 73 74 61 74 65 20 6f 66 20 53 51 4c 69 ** state of SQLi
386e0 74 65 20 61 6e 64 20 74 6f 20 69 6e 6a 65 63 74 te and to inject
386f0 20 66 61 75 6c 74 73 20 69 6e 74 6f 20 53 51 4c faults into SQL
38700 69 74 65 20 66 6f 72 20 74 65 73 74 69 6e 67 0a ite for testing.
38710 2a 2a 20 70 75 72 70 6f 73 65 73 2e 20 20 54 68 ** purposes. Th
38720 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
38730 72 20 69 73 20 61 6e 20 6f 70 65 72 61 74 69 6f r is an operatio
38740 6e 20 63 6f 64 65 20 74 68 61 74 20 64 65 74 65 n code that dete
38750 72 6d 69 6e 65 73 0a 2a 2a 20 74 68 65 20 6e 75 rmines.** the nu
38760 6d 62 65 72 2c 20 6d 65 61 6e 69 6e 67 2c 20 61 mber, meaning, a
38770 6e 64 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 nd operation of
38780 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 70 all subsequent p
38790 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a arameters..**.**
387a0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 This interface
387b0 69 73 20 6e 6f 74 20 66 6f 72 20 75 73 65 20 62 is not for use b
387c0 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 2e 20 y applications.
387d0 20 49 74 20 65 78 69 73 74 73 20 73 6f 6c 65 6c It exists solel
387e0 79 0a 2a 2a 20 66 6f 72 20 76 65 72 69 66 79 69 y.** for verifyi
387f0 6e 67 20 74 68 65 20 63 6f 72 72 65 63 74 20 6f ng the correct o
38800 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 peration of the
38810 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 SQLite library.
38820 20 44 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e Depending.** on
38830 20 68 6f 77 20 74 68 65 20 53 51 4c 69 74 65 20 how the SQLite
38840 6c 69 62 72 61 72 79 20 69 73 20 63 6f 6d 70 69 library is compi
38850 6c 65 64 2c 20 74 68 69 73 20 69 6e 74 65 72 66 led, this interf
38860 61 63 65 20 6d 69 67 68 74 20 6e 6f 74 20 65 78 ace might not ex
38870 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 ist..**.** The d
38880 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 6f 70 etails of the op
38890 65 72 61 74 69 6f 6e 20 63 6f 64 65 73 2c 20 74 eration codes, t
388a0 68 65 69 72 20 6d 65 61 6e 69 6e 67 73 2c 20 74 heir meanings, t
388b0 68 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a he parameters.**
388c0 20 74 68 65 79 20 74 61 6b 65 2c 20 61 6e 64 20 they take, and
388d0 77 68 61 74 20 74 68 65 79 20 64 6f 20 61 72 65 what they do are
388e0 20 61 6c 6c 20 73 75 62 6a 65 63 74 20 74 6f 20 all subject to
388f0 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e change without n
38900 6f 74 69 63 65 2e 0a 2a 2a 20 55 6e 6c 69 6b 65 otice..** Unlike
38910 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 53 51 4c most of the SQL
38920 69 74 65 20 41 50 49 2c 20 74 68 69 73 20 66 75 ite API, this fu
38930 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 75 nction is not gu
38940 61 72 61 6e 74 65 65 64 20 74 6f 0a 2a 2a 20 6f aranteed to.** o
38950 70 65 72 61 74 65 20 63 6f 6e 73 69 73 74 65 6e perate consisten
38960 74 6c 79 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c tly from one rel
38970 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 ease to the next
38980 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
38990 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 65 73 74 int sqlite3_test
389a0 5f 63 6f 6e 74 72 6f 6c 28 69 6e 74 20 6f 70 2c _control(int op,
389b0 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ...);../*.** CA
389c0 50 49 33 52 45 46 3a 20 54 65 73 74 69 6e 67 20 PI3REF: Testing
389d0 49 6e 74 65 72 66 61 63 65 20 4f 70 65 72 61 74 Interface Operat
389e0 69 6f 6e 20 43 6f 64 65 73 20 7b 48 31 31 34 31 ion Codes {H1141
389f0 30 7d 20 3c 48 31 31 34 30 30 3e 0a 2a 2a 0a 2a 0} <H11400>.**.*
38a00 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 * These constant
38a10 73 20 61 72 65 20 74 68 65 20 76 61 6c 69 64 20 s are the valid
38a20 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 65 20 70 operation code p
38a30 61 72 61 6d 65 74 65 72 73 20 75 73 65 64 0a 2a arameters used.*
38a40 2a 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 * as the first a
38a50 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 rgument to [sqli
38a60 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c te3_test_control
38a70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ()]..**.** These
38a80 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 parameters and
38a90 74 68 65 69 72 20 6d 65 61 6e 69 6e 67 73 20 61 their meanings a
38aa0 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 re subject to ch
38ab0 61 6e 67 65 0a 2a 2a 20 77 69 74 68 6f 75 74 20 ange.** without
38ac0 6e 6f 74 69 63 65 2e 20 20 54 68 65 73 65 20 76 notice. These v
38ad0 61 6c 75 65 73 20 61 72 65 20 66 6f 72 20 74 65 alues are for te
38ae0 73 74 69 6e 67 20 70 75 72 70 6f 73 65 73 20 6f sting purposes o
38af0 6e 6c 79 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 nly..** Applicat
38b00 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 ions should not
38b10 75 73 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 use any of these
38b20 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 74 parameters or t
38b30 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 he.** [sqlite3_t
38b40 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 est_control()] i
38b50 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 nterface..*/.#de
38b60 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 fine SQLITE_TEST
38b70 43 54 52 4c 5f 50 52 4e 47 5f 53 41 56 45 20 20 CTRL_PRNG_SAVE
38b80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 5.
38b90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
38ba0 45 53 54 43 54 52 4c 5f 50 52 4e 47 5f 52 45 53 ESTCTRL_PRNG_RES
38bb0 54 4f 52 45 20 20 20 20 20 20 20 20 20 20 20 20 TORE
38bc0 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 6.#define SQLIT
38bd0 45 5f 54 45 53 54 43 54 52 4c 5f 50 52 4e 47 5f E_TESTCTRL_PRNG_
38be0 52 45 53 45 54 20 20 20 20 20 20 20 20 20 20 20 RESET
38bf0 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 7.#define SQ
38c00 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 42 49 LITE_TESTCTRL_BI
38c10 54 56 45 43 5f 54 45 53 54 20 20 20 20 20 20 20 TVEC_TEST
38c20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 8.#define
38c30 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c SQLITE_TESTCTRL
38c40 5f 46 41 55 4c 54 5f 49 4e 53 54 41 4c 4c 20 20 _FAULT_INSTALL
38c50 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 9.#def
38c60 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 ine SQLITE_TESTC
38c70 54 52 4c 5f 42 45 4e 49 47 4e 5f 4d 41 4c 4c 4f TRL_BENIGN_MALLO
38c80 43 5f 48 4f 4f 4b 53 20 20 20 20 20 31 30 0a 23 C_HOOKS 10.#
38c90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 define SQLITE_TE
38ca0 53 54 43 54 52 4c 5f 50 45 4e 44 49 4e 47 5f 42 STCTRL_PENDING_B
38cb0 59 54 45 20 20 20 20 20 20 20 20 20 20 20 20 31 YTE 1
38cc0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
38cd0 5f 54 45 53 54 43 54 52 4c 5f 41 53 53 45 52 54 _TESTCTRL_ASSERT
38ce0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
38cf0 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 12.#define SQL
38d00 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 41 4c 57 ITE_TESTCTRL_ALW
38d10 41 59 53 20 20 20 20 20 20 20 20 20 20 20 20 20 AYS
38d20 20 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 13.#define
38d30 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f SQLITE_TESTCTRL_
38d40 52 45 53 45 52 56 45 20 20 20 20 20 20 20 20 20 RESERVE
38d50 20 20 20 20 20 20 20 20 31 34 0a 0a 2f 2a 0a 2a 14../*.*
38d60 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 69 * CAPI3REF: SQLi
38d70 74 65 20 52 75 6e 74 69 6d 65 20 53 74 61 74 75 te Runtime Statu
38d80 73 20 7b 48 31 37 32 30 30 7d 20 3c 53 36 30 32 s {H17200} <S602
38d90 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 00>.** EXPERIMEN
38da0 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 TAL.**.** This i
38db0 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 nterface is used
38dc0 20 74 6f 20 72 65 74 72 69 65 76 65 20 72 75 6e to retrieve run
38dd0 74 69 6d 65 20 73 74 61 74 75 73 20 69 6e 66 6f time status info
38de0 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 rmation.** about
38df0 20 74 68 65 20 70 72 65 66 6f 72 6d 61 6e 63 65 the preformance
38e00 20 6f 66 20 53 51 4c 69 74 65 2c 20 61 6e 64 20 of SQLite, and
38e10 6f 70 74 69 6f 6e 61 6c 6c 79 20 74 6f 20 72 65 optionally to re
38e20 73 65 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 68 set various.** h
38e30 69 67 68 77 61 74 65 72 20 6d 61 72 6b 73 2e 20 ighwater marks.
38e40 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
38e50 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 ent is an intege
38e60 72 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 r code for.** th
38e70 65 20 73 70 65 63 69 66 69 63 20 70 61 72 61 6d e specific param
38e80 65 74 65 72 20 74 6f 20 6d 65 61 73 75 72 65 2e eter to measure.
38e90 20 20 52 65 63 6f 67 6e 69 7a 65 64 20 69 6e 74 Recognized int
38ea0 65 67 65 72 20 63 6f 64 65 73 0a 2a 2a 20 61 72 eger codes.** ar
38eb0 65 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 5b 53 e of the form [S
38ec0 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 45 4d QLITE_STATUS_MEM
38ed0 4f 52 59 5f 55 53 45 44 20 7c 20 53 51 4c 49 54 ORY_USED | SQLIT
38ee0 45 5f 53 54 41 54 55 53 5f 2e 2e 2e 5d 2e 0a 2a E_STATUS_...]..*
38ef0 2a 20 54 68 65 20 63 75 72 72 65 6e 74 20 76 61 * The current va
38f00 6c 75 65 20 6f 66 20 74 68 65 20 70 61 72 61 6d lue of the param
38f10 65 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 eter is returned
38f20 20 69 6e 74 6f 20 2a 70 43 75 72 72 65 6e 74 2e into *pCurrent.
38f30 0a 2a 2a 20 54 68 65 20 68 69 67 68 65 73 74 20 .** The highest
38f40 72 65 63 6f 72 64 65 64 20 76 61 6c 75 65 20 69 recorded value i
38f50 73 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 s returned in *p
38f60 48 69 67 68 77 61 74 65 72 2e 20 20 49 66 20 74 Highwater. If t
38f70 68 65 0a 2a 2a 20 72 65 73 65 74 46 6c 61 67 20 he.** resetFlag
38f80 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 is true, then th
38f90 65 20 68 69 67 68 65 73 74 20 72 65 63 6f 72 64 e highest record
38fa0 20 76 61 6c 75 65 20 69 73 20 72 65 73 65 74 20 value is reset
38fb0 61 66 74 65 72 0a 2a 2a 20 2a 70 48 69 67 68 77 after.** *pHighw
38fc0 61 74 65 72 20 69 73 20 77 72 69 74 74 65 6e 2e ater is written.
38fd0 20 53 6f 6d 65 20 70 61 72 61 6d 65 74 65 72 73 Some parameters
38fe0 20 64 6f 20 6e 6f 74 20 72 65 63 6f 72 64 20 74 do not record t
38ff0 68 65 20 68 69 67 68 65 73 74 0a 2a 2a 20 76 61 he highest.** va
39000 6c 75 65 2e 20 20 46 6f 72 20 74 68 6f 73 65 20 lue. For those
39010 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6e 6f parameters.** no
39020 74 68 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e thing is written
39030 20 69 6e 74 6f 20 2a 70 48 69 67 68 77 61 74 65 into *pHighwate
39040 72 20 61 6e 64 20 74 68 65 20 72 65 73 65 74 46 r and the resetF
39050 6c 61 67 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a lag is ignored..
39060 2a 2a 20 4f 74 68 65 72 20 70 61 72 61 6d 65 74 ** Other paramet
39070 65 72 73 20 72 65 63 6f 72 64 20 6f 6e 6c 79 20 ers record only
39080 74 68 65 20 68 69 67 68 77 61 74 65 72 20 6d 61 the highwater ma
39090 72 6b 20 61 6e 64 20 6e 6f 74 20 74 68 65 20 63 rk and not the c
390a0 75 72 72 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 2e urrent.** value.
390b0 20 20 46 6f 72 20 74 68 65 73 65 20 6c 61 74 74 For these latt
390c0 65 72 20 70 61 72 61 6d 65 74 65 72 73 20 6e 6f er parameters no
390d0 74 68 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e thing is written
390e0 20 69 6e 74 6f 20 2a 70 43 75 72 72 65 6e 74 2e into *pCurrent.
390f0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
39100 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49 ine returns SQLI
39110 54 45 5f 4f 4b 20 6f 6e 20 73 75 63 63 65 73 73 TE_OK on success
39120 20 61 6e 64 20 61 20 6e 6f 6e 2d 7a 65 72 6f 0a and a non-zero.
39130 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 ** [error code]
39140 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a on failure..**.*
39150 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 * This routine i
39160 73 20 74 68 72 65 61 64 73 61 66 65 20 62 75 74 s threadsafe but
39170 20 69 73 20 6e 6f 74 20 61 74 6f 6d 69 63 2e 20 is not atomic.
39180 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 This routine ca
39190 6e 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 77 n be.** called w
391a0 68 69 6c 65 20 6f 74 68 65 72 20 74 68 72 65 61 hile other threa
391b0 64 73 20 61 72 65 20 72 75 6e 6e 69 6e 67 20 74 ds are running t
391c0 68 65 20 73 61 6d 65 20 6f 72 20 64 69 66 66 65 he same or diffe
391d0 72 65 6e 74 20 53 51 4c 69 74 65 0a 2a 2a 20 69 rent SQLite.** i
391e0 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 nterfaces. Howe
391f0 76 65 72 20 74 68 65 20 76 61 6c 75 65 73 20 72 ver the values r
39200 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 43 75 72 eturned in *pCur
39210 72 65 6e 74 20 61 6e 64 0a 2a 2a 20 2a 70 48 69 rent and.** *pHi
39220 67 68 77 61 74 65 72 20 72 65 66 6c 65 63 74 20 ghwater reflect
39230 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 53 51 the status of SQ
39240 4c 69 74 65 20 61 74 20 64 69 66 66 65 72 65 6e Lite at differen
39250 74 20 70 6f 69 6e 74 73 20 69 6e 20 74 69 6d 65 t points in time
39260 0a 2a 2a 20 61 6e 64 20 69 74 20 69 73 20 70 6f .** and it is po
39270 73 73 69 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 ssible that anot
39280 68 65 72 20 74 68 72 65 61 64 20 6d 69 67 68 74 her thread might
39290 20 63 68 61 6e 67 65 20 74 68 65 20 70 61 72 61 change the para
392a0 6d 65 74 65 72 0a 2a 2a 20 69 6e 20 62 65 74 77 meter.** in betw
392b0 65 65 6e 20 74 68 65 20 74 69 6d 65 73 20 77 68 een the times wh
392c0 65 6e 20 2a 70 43 75 72 72 65 6e 74 20 61 6e 64 en *pCurrent and
392d0 20 2a 70 48 69 67 68 77 61 74 65 72 20 61 72 65 *pHighwater are
392e0 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 written..**.**
392f0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 See also: [sqlit
39300 65 33 5f 64 62 5f 73 74 61 74 75 73 28 29 5d 0a e3_db_status()].
39310 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 */.SQLITE_API SQ
39320 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 LITE_EXPERIMENTA
39330 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 L int sqlite3_st
39340 61 74 75 73 28 69 6e 74 20 6f 70 2c 20 69 6e 74 atus(int op, int
39350 20 2a 70 43 75 72 72 65 6e 74 2c 20 69 6e 74 20 *pCurrent, int
39360 2a 70 48 69 67 68 77 61 74 65 72 2c 20 69 6e 74 *pHighwater, int
39370 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 0a 2f resetFlag);.../
39380 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
39390 74 61 74 75 73 20 50 61 72 61 6d 65 74 65 72 73 tatus Parameters
393a0 20 7b 48 31 37 32 35 30 7d 20 3c 48 31 37 32 30 {H17250} <H1720
393b0 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 0>.** EXPERIMENT
393c0 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 AL.**.** These i
393d0 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 nteger constants
393e0 20 64 65 73 69 67 6e 61 74 65 20 76 61 72 69 6f designate vario
393f0 75 73 20 72 75 6e 2d 74 69 6d 65 20 73 74 61 74 us run-time stat
39400 75 73 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a us parameters.**
39410 20 74 68 61 74 20 63 61 6e 20 62 65 20 72 65 74 that can be ret
39420 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 urned by [sqlite
39430 33 5f 73 74 61 74 75 73 28 29 5d 2e 0a 2a 2a 0a 3_status()]..**.
39440 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 ** <dl>.** <dt>S
39450 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 45 4d QLITE_STATUS_MEM
39460 4f 52 59 5f 55 53 45 44 3c 2f 64 74 3e 0a 2a 2a ORY_USED</dt>.**
39470 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 <dd>This parame
39480 74 65 72 20 69 73 20 74 68 65 20 63 75 72 72 65 ter is the curre
39490 6e 74 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d nt amount of mem
394a0 6f 72 79 20 63 68 65 63 6b 65 64 20 6f 75 74 0a ory checked out.
394b0 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ** using [sqlite
394c0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 65 69 74 3_malloc()], eit
394d0 68 65 72 20 64 69 72 65 63 74 6c 79 20 6f 72 20 her directly or
394e0 69 6e 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 indirectly. The
394f0 0a 2a 2a 20 66 69 67 75 72 65 20 69 6e 63 6c 75 .** figure inclu
39500 64 65 73 20 63 61 6c 6c 73 20 6d 61 64 65 20 74 des calls made t
39510 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f o [sqlite3_mallo
39520 63 28 29 5d 20 62 79 20 74 68 65 20 61 70 70 6c c()] by the appl
39530 69 63 61 74 69 6f 6e 0a 2a 2a 20 61 6e 64 20 69 ication.** and i
39540 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 75 nternal memory u
39550 73 61 67 65 20 62 79 20 74 68 65 20 53 51 4c 69 sage by the SQLi
39560 74 65 20 6c 69 62 72 61 72 79 2e 20 20 53 63 72 te library. Scr
39570 61 74 63 68 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 atch memory.** c
39580 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 5b 53 51 ontrolled by [SQ
39590 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 LITE_CONFIG_SCRA
395a0 54 43 48 5d 20 61 6e 64 20 61 75 78 69 6c 69 61 TCH] and auxilia
395b0 72 79 20 70 61 67 65 2d 63 61 63 68 65 0a 2a 2a ry page-cache.**
395c0 20 6d 65 6d 6f 72 79 20 63 6f 6e 74 72 6f 6c 6c memory controll
395d0 65 64 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f ed by [SQLITE_CO
395e0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 20 NFIG_PAGECACHE]
395f0 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 is not included
39600 69 6e 0a 2a 2a 20 74 68 69 73 20 70 61 72 61 6d in.** this param
39610 65 74 65 72 2e 20 20 54 68 65 20 61 6d 6f 75 6e eter. The amoun
39620 74 20 72 65 74 75 72 6e 65 64 20 69 73 20 74 68 t returned is th
39630 65 20 73 75 6d 20 6f 66 20 74 68 65 20 61 6c 6c e sum of the all
39640 6f 63 61 74 69 6f 6e 0a 2a 2a 20 73 69 7a 65 73 ocation.** sizes
39650 20 61 73 20 72 65 70 6f 72 74 65 64 20 62 79 20 as reported by
39660 74 68 65 20 78 53 69 7a 65 20 6d 65 74 68 6f 64 the xSize method
39670 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d in [sqlite3_mem
39680 5f 6d 65 74 68 6f 64 73 5d 2e 3c 2f 64 64 3e 0a _methods].</dd>.
39690 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
396a0 5f 53 54 41 54 55 53 5f 4d 41 4c 4c 4f 43 5f 53 _STATUS_MALLOC_S
396b0 49 5a 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e IZE</dt>.** <dd>
396c0 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 This parameter r
396d0 65 63 6f 72 64 73 20 74 68 65 20 6c 61 72 67 65 ecords the large
396e0 73 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 st memory alloca
396f0 74 69 6f 6e 20 72 65 71 75 65 73 74 0a 2a 2a 20 tion request.**
39700 68 61 6e 64 65 64 20 74 6f 20 5b 73 71 6c 69 74 handed to [sqlit
39710 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 e3_malloc()] or
39720 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 [sqlite3_realloc
39730 28 29 5d 20 28 6f 72 20 74 68 65 69 72 0a 2a 2a ()] (or their.**
39740 20 69 6e 74 65 72 6e 61 6c 20 65 71 75 69 76 61 internal equiva
39750 6c 65 6e 74 73 29 2e 20 20 4f 6e 6c 79 20 74 68 lents). Only th
39760 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
39770 20 69 6e 20 74 68 65 0a 2a 2a 20 2a 70 48 69 67 in the.** *pHig
39780 68 77 61 74 65 72 20 70 61 72 61 6d 65 74 65 72 hwater parameter
39790 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 to [sqlite3_sta
397a0 74 75 73 28 29 5d 20 69 73 20 6f 66 20 69 6e 74 tus()] is of int
397b0 65 72 65 73 74 2e 20 20 0a 2a 2a 20 54 68 65 20 erest. .** The
397c0 76 61 6c 75 65 20 77 72 69 74 74 65 6e 20 69 6e value written in
397d0 74 6f 20 74 68 65 20 2a 70 43 75 72 72 65 6e 74 to the *pCurrent
397e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 6e parameter is un
397f0 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a defined.</dd>.**
39800 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 .** <dt>SQLITE_S
39810 54 41 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f TATUS_PAGECACHE_
39820 55 53 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 USED</dt>.** <dd
39830 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 >This parameter
39840 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
39850 65 72 20 6f 66 20 70 61 67 65 73 20 75 73 65 64 er of pages used
39860 20 6f 75 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b out of the.** [
39870 70 61 67 65 63 61 63 68 65 20 6d 65 6d 6f 72 79 pagecache memory
39880 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 74 68 61 74 allocator] that
39890 20 77 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20 was configured
398a0 75 73 69 6e 67 20 0a 2a 2a 20 5b 53 51 4c 49 54 using .** [SQLIT
398b0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 E_CONFIG_PAGECAC
398c0 48 45 5d 2e 20 20 54 68 65 0a 2a 2a 20 76 61 6c HE]. The.** val
398d0 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 69 ue returned is i
398e0 6e 20 70 61 67 65 73 2c 20 6e 6f 74 20 69 6e 20 n pages, not in
398f0 62 79 74 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a bytes.</dd>.**.*
39900 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 * <dt>SQLITE_STA
39910 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f 4f 56 TUS_PAGECACHE_OV
39920 45 52 46 4c 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c ERFLOW</dt>.** <
39930 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65 dd>This paramete
39940 72 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 r returns the nu
39950 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 mber of bytes of
39960 20 70 61 67 65 20 63 61 63 68 65 0a 2a 2a 20 61 page cache.** a
39970 6c 6c 6f 63 61 74 69 6f 6e 20 77 68 69 63 68 20 llocation which
39980 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 73 74 61 could not be sta
39990 74 69 73 66 69 65 64 20 62 79 20 74 68 65 20 5b tisfied by the [
399a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 SQLITE_CONFIG_PA
399b0 47 45 43 41 43 48 45 5d 0a 2a 2a 20 62 75 66 66 GECACHE].** buff
399c0 65 72 20 61 6e 64 20 77 68 65 72 65 20 66 6f 72 er and where for
399d0 63 65 64 20 74 6f 20 6f 76 65 72 66 6c 6f 77 20 ced to overflow
399e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c to [sqlite3_mall
399f0 6f 63 28 29 5d 2e 20 20 54 68 65 0a 2a 2a 20 72 oc()]. The.** r
39a00 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 6e eturned value in
39a10 63 6c 75 64 65 73 20 61 6c 6c 6f 63 61 74 69 6f cludes allocatio
39a20 6e 73 20 74 68 61 74 20 6f 76 65 72 66 6c 6f 77 ns that overflow
39a30 65 64 20 62 65 63 61 75 73 65 20 74 68 65 79 0a ed because they.
39a40 2a 2a 20 77 68 65 72 65 20 74 6f 6f 20 6c 61 72 ** where too lar
39a50 67 65 20 28 74 68 65 79 20 77 65 72 65 20 6c 61 ge (they were la
39a60 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 22 73 rger than the "s
39a70 7a 22 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a z" parameter to.
39a80 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ** [SQLITE_CONFI
39a90 47 5f 50 41 47 45 43 41 43 48 45 5d 29 20 61 6e G_PAGECACHE]) an
39aa0 64 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 74 68 d allocations th
39ab0 61 74 20 6f 76 65 72 66 6c 6f 77 65 64 20 62 65 at overflowed be
39ac0 63 61 75 73 65 0a 2a 2a 20 6e 6f 20 73 70 61 63 cause.** no spac
39ad0 65 20 77 61 73 20 6c 65 66 74 20 69 6e 20 74 68 e was left in th
39ae0 65 20 70 61 67 65 20 63 61 63 68 65 2e 3c 2f 64 e page cache.</d
39af0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
39b00 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45 43 ITE_STATUS_PAGEC
39b10 41 43 48 45 5f 53 49 5a 45 3c 2f 64 74 3e 0a 2a ACHE_SIZE</dt>.*
39b20 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d * <dd>This param
39b30 65 74 65 72 20 72 65 63 6f 72 64 73 20 74 68 65 eter records the
39b40 20 6c 61 72 67 65 73 74 20 6d 65 6d 6f 72 79 20 largest memory
39b50 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 allocation reque
39b60 73 74 0a 2a 2a 20 68 61 6e 64 65 64 20 74 6f 20 st.** handed to
39b70 5b 70 61 67 65 63 61 63 68 65 20 6d 65 6d 6f 72 [pagecache memor
39b80 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 2e 20 20 4f y allocator]. O
39b90 6e 6c 79 20 74 68 65 20 76 61 6c 75 65 20 72 65 nly the value re
39ba0 74 75 72 6e 65 64 20 69 6e 20 74 68 65 0a 2a 2a turned in the.**
39bb0 20 2a 70 48 69 67 68 77 61 74 65 72 20 70 61 72 *pHighwater par
39bc0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 ameter to [sqlit
39bd0 65 33 5f 73 74 61 74 75 73 28 29 5d 20 69 73 20 e3_status()] is
39be0 6f 66 20 69 6e 74 65 72 65 73 74 2e 20 20 0a 2a of interest. .*
39bf0 2a 20 54 68 65 20 76 61 6c 75 65 20 77 72 69 74 * The value writ
39c00 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 2a 70 43 ten into the *pC
39c10 75 72 72 65 6e 74 20 70 61 72 61 6d 65 74 65 72 urrent parameter
39c20 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f is undefined.</
39c30 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
39c40 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41 LITE_STATUS_SCRA
39c50 54 43 48 5f 55 53 45 44 3c 2f 64 74 3e 0a 2a 2a TCH_USED</dt>.**
39c60 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 <dd>This parame
39c70 74 65 72 20 72 65 74 75 72 6e 73 20 74 68 65 20 ter returns the
39c80 6e 75 6d 62 65 72 20 6f 66 20 61 6c 6c 6f 63 61 number of alloca
39c90 74 69 6f 6e 73 20 75 73 65 64 20 6f 75 74 20 6f tions used out o
39ca0 66 20 74 68 65 0a 2a 2a 20 5b 73 63 72 61 74 63 f the.** [scratc
39cb0 68 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 h memory allocat
39cc0 6f 72 5d 20 63 6f 6e 66 69 67 75 72 65 64 20 75 or] configured u
39cd0 73 69 6e 67 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f sing.** [SQLITE_
39ce0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 2e CONFIG_SCRATCH].
39cf0 20 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 The value retu
39d00 72 6e 65 64 20 69 73 20 69 6e 20 61 6c 6c 6f 63 rned is in alloc
39d10 61 74 69 6f 6e 73 2c 20 6e 6f 74 0a 2a 2a 20 69 ations, not.** i
39d20 6e 20 62 79 74 65 73 2e 20 20 53 69 6e 63 65 20 n bytes. Since
39d30 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 20 a single thread
39d40 6d 61 79 20 6f 6e 6c 79 20 68 61 76 65 20 6f 6e may only have on
39d50 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 e scratch alloca
39d60 74 69 6f 6e 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 tion.** outstand
39d70 69 6e 67 20 61 74 20 74 69 6d 65 2c 20 74 68 69 ing at time, thi
39d80 73 20 70 61 72 61 6d 65 74 65 72 20 61 6c 73 6f s parameter also
39d90 20 72 65 70 6f 72 74 73 20 74 68 65 20 6e 75 6d reports the num
39da0 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 0a 2a ber of threads.*
39db0 2a 20 75 73 69 6e 67 20 73 63 72 61 74 63 68 20 * using scratch
39dc0 6d 65 6d 6f 72 79 20 61 74 20 74 68 65 20 73 61 memory at the sa
39dd0 6d 65 20 74 69 6d 65 2e 3c 2f 64 64 3e 0a 2a 2a me time.</dd>.**
39de0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 .** <dt>SQLITE_S
39df0 54 41 54 55 53 5f 53 43 52 41 54 43 48 5f 4f 56 TATUS_SCRATCH_OV
39e00 45 52 46 4c 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c ERFLOW</dt>.** <
39e10 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65 dd>This paramete
39e20 72 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 r returns the nu
39e30 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 mber of bytes of
39e40 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 0a scratch memory.
39e50 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 77 68 ** allocation wh
39e60 69 63 68 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 ich could not be
39e70 20 73 74 61 74 69 73 66 69 65 64 20 62 79 20 74 statisfied by t
39e80 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 he [SQLITE_CONFI
39e90 47 5f 53 43 52 41 54 43 48 5d 0a 2a 2a 20 62 75 G_SCRATCH].** bu
39ea0 66 66 65 72 20 61 6e 64 20 77 68 65 72 65 20 66 ffer and where f
39eb0 6f 72 63 65 64 20 74 6f 20 6f 76 65 72 66 6c 6f orced to overflo
39ec0 77 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 w to [sqlite3_ma
39ed0 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 76 61 lloc()]. The va
39ee0 6c 75 65 73 0a 2a 2a 20 72 65 74 75 72 6e 65 64 lues.** returned
39ef0 20 69 6e 63 6c 75 64 65 20 6f 76 65 72 66 6c 6f include overflo
39f00 77 73 20 62 65 63 61 75 73 65 20 74 68 65 20 72 ws because the r
39f10 65 71 75 65 73 74 65 64 20 61 6c 6c 6f 63 61 74 equested allocat
39f20 69 6f 6e 20 77 61 73 20 74 6f 6f 0a 2a 2a 20 6c ion was too.** l
39f30 61 72 67 65 72 20 28 74 68 61 74 20 69 73 2c 20 arger (that is,
39f40 62 65 63 61 75 73 65 20 74 68 65 20 72 65 71 75 because the requ
39f50 65 73 74 65 64 20 61 6c 6c 6f 63 61 74 69 6f 6e ested allocation
39f60 20 77 61 73 20 6c 61 72 67 65 72 20 74 68 61 6e was larger than
39f70 20 74 68 65 0a 2a 2a 20 22 73 7a 22 20 70 61 72 the.** "sz" par
39f80 61 6d 65 74 65 72 20 74 6f 20 5b 53 51 4c 49 54 ameter to [SQLIT
39f90 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 E_CONFIG_SCRATCH
39fa0 5d 29 20 61 6e 64 20 62 65 63 61 75 73 65 20 6e ]) and because n
39fb0 6f 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 o scratch buffer
39fc0 0a 2a 2a 20 73 6c 6f 74 73 20 77 65 72 65 20 61 .** slots were a
39fd0 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 3c 2f 64 vailable..** </d
39fe0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
39ff0 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54 ITE_STATUS_SCRAT
3a000 43 48 5f 53 49 5a 45 3c 2f 64 74 3e 0a 2a 2a 20 CH_SIZE</dt>.**
3a010 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 <dd>This paramet
3a020 65 72 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c er records the l
3a030 61 72 67 65 73 74 20 6d 65 6d 6f 72 79 20 61 6c argest memory al
3a040 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 location request
3a050 0a 2a 2a 20 68 61 6e 64 65 64 20 74 6f 20 5b 73 .** handed to [s
3a060 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 61 6c cratch memory al
3a070 6c 6f 63 61 74 6f 72 5d 2e 20 20 4f 6e 6c 79 20 locator]. Only
3a080 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
3a090 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 2a 70 48 ed in the.** *pH
3a0a0 69 67 68 77 61 74 65 72 20 70 61 72 61 6d 65 74 ighwater paramet
3a0b0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 er to [sqlite3_s
3a0c0 74 61 74 75 73 28 29 5d 20 69 73 20 6f 66 20 69 tatus()] is of i
3a0d0 6e 74 65 72 65 73 74 2e 20 20 0a 2a 2a 20 54 68 nterest. .** Th
3a0e0 65 20 76 61 6c 75 65 20 77 72 69 74 74 65 6e 20 e value written
3a0f0 69 6e 74 6f 20 74 68 65 20 2a 70 43 75 72 72 65 into the *pCurre
3a100 6e 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nt parameter is
3a110 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a undefined.</dd>.
3a120 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
3a130 5f 53 54 41 54 55 53 5f 50 41 52 53 45 52 5f 53 _STATUS_PARSER_S
3a140 54 41 43 4b 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 TACK</dt>.** <dd
3a150 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 >This parameter
3a160 72 65 63 6f 72 64 73 20 74 68 65 20 64 65 65 70 records the deep
3a170 65 73 74 20 70 61 72 73 65 72 20 73 74 61 63 6b est parser stack
3a180 2e 20 20 49 74 20 69 73 20 6f 6e 6c 79 0a 2a 2a . It is only.**
3a190 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 53 meaningful if S
3a1a0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
3a1b0 64 20 77 69 74 68 20 5b 59 59 54 52 41 43 4b 4d d with [YYTRACKM
3a1c0 41 58 53 54 41 43 4b 44 45 50 54 48 5d 2e 3c 2f AXSTACKDEPTH].</
3a1d0 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a dd>.** </dl>.**.
3a1e0 2a 2a 20 4e 65 77 20 73 74 61 74 75 73 20 70 61 ** New status pa
3a1f0 72 61 6d 65 74 65 72 73 20 6d 61 79 20 62 65 20 rameters may be
3a200 61 64 64 65 64 20 66 72 6f 6d 20 74 69 6d 65 20 added from time
3a210 74 6f 20 74 69 6d 65 2e 0a 2a 2f 0a 23 64 65 66 to time..*/.#def
3a220 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 ine SQLITE_STATU
3a230 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 20 20 20 S_MEMORY_USED
3a240 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 0.#define
3a250 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 SQLITE_STATUS_P
3a260 41 47 45 43 41 43 48 45 5f 55 53 45 44 20 20 20 AGECACHE_USED
3a270 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 1.#define SQ
3a280 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45 LITE_STATUS_PAGE
3a290 43 41 43 48 45 5f 4f 56 45 52 46 4c 4f 57 20 20 CACHE_OVERFLOW
3a2a0 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 2.#define SQLIT
3a2b0 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54 43 48 E_STATUS_SCRATCH
3a2c0 5f 55 53 45 44 20 20 20 20 20 20 20 20 20 33 0a _USED 3.
3a2d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
3a2e0 54 41 54 55 53 5f 53 43 52 41 54 43 48 5f 4f 56 TATUS_SCRATCH_OV
3a2f0 45 52 46 4c 4f 57 20 20 20 20 20 34 0a 23 64 65 ERFLOW 4.#de
3a300 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 fine SQLITE_STAT
3a310 55 53 5f 4d 41 4c 4c 4f 43 5f 53 49 5a 45 20 20 US_MALLOC_SIZE
3a320 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 5.#defin
3a330 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f e SQLITE_STATUS_
3a340 50 41 52 53 45 52 5f 53 54 41 43 4b 20 20 20 20 PARSER_STACK
3a350 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 6.#define S
3a360 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 QLITE_STATUS_PAG
3a370 45 43 41 43 48 45 5f 53 49 5a 45 20 20 20 20 20 ECACHE_SIZE
3a380 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 7.#define SQLI
3a390 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54 43 TE_STATUS_SCRATC
3a3a0 48 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 38 H_SIZE 8
3a3b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
3a3c0 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 : Database Conne
3a3d0 63 74 69 6f 6e 20 53 74 61 74 75 73 20 7b 48 31 ction Status {H1
3a3e0 37 35 30 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 7500} <S60200>.*
3a3f0 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a * EXPERIMENTAL.*
3a400 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 *.** This interf
3a410 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 ace is used to r
3a420 65 74 72 69 65 76 65 20 72 75 6e 74 69 6d 65 20 etrieve runtime
3a430 73 74 61 74 75 73 20 69 6e 66 6f 72 6d 61 74 69 status informati
3a440 6f 6e 20 0a 2a 2a 20 61 62 6f 75 74 20 61 20 73 on .** about a s
3a450 69 6e 67 6c 65 20 5b 64 61 74 61 62 61 73 65 20 ingle [database
3a460 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 connection]. Th
3a470 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
3a480 20 69 73 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 is the.** datab
3a490 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f ase connection o
3a4a0 62 6a 65 63 74 20 74 6f 20 62 65 20 69 6e 74 65 bject to be inte
3a4b0 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20 73 rrogated. The s
3a4c0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 0a 2a econd argument.*
3a4d0 2a 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 * is the paramet
3a4e0 65 72 20 74 6f 20 69 6e 74 65 72 72 6f 67 61 74 er to interrogat
3a4f0 65 2e 20 20 43 75 72 72 65 6e 74 6c 79 2c 20 74 e. Currently, t
3a500 68 65 20 6f 6e 6c 79 20 61 6c 6c 6f 77 65 64 20 he only allowed
3a510 76 61 6c 75 65 0a 2a 2a 20 66 6f 72 20 74 68 65 value.** for the
3a520 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
3a530 72 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 42 53 r is [SQLITE_DBS
3a540 54 41 54 55 53 5f 4c 4f 4f 4b 41 53 49 44 45 5f TATUS_LOOKASIDE_
3a550 55 53 45 44 5d 2e 0a 2a 2a 20 41 64 64 69 74 69 USED]..** Additi
3a560 6f 6e 61 6c 20 6f 70 74 69 6f 6e 73 20 77 69 6c onal options wil
3a570 6c 20 6c 69 6b 65 6c 79 20 61 70 70 65 61 72 20 l likely appear
3a580 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
3a590 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a es of SQLite..**
3a5a0 0a 2a 2a 20 54 68 65 20 63 75 72 72 65 6e 74 20 .** The current
3a5b0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 72 65 71 value of the req
3a5c0 75 65 73 74 65 64 20 70 61 72 61 6d 65 74 65 72 uested parameter
3a5d0 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f is written into
3a5e0 20 2a 70 43 75 72 0a 2a 2a 20 61 6e 64 20 74 68 *pCur.** and th
3a5f0 65 20 68 69 67 68 65 73 74 20 69 6e 73 74 61 6e e highest instan
3a600 74 61 6e 65 6f 75 73 20 76 61 6c 75 65 20 69 73 taneous value is
3a610 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 written into *p
3a620 48 69 77 74 72 2e 20 20 49 66 0a 2a 2a 20 74 68 Hiwtr. If.** th
3a630 65 20 72 65 73 65 74 46 6c 67 20 69 73 20 74 72 e resetFlg is tr
3a640 75 65 2c 20 74 68 65 6e 20 74 68 65 20 68 69 67 ue, then the hig
3a650 68 65 73 74 20 69 6e 73 74 61 6e 74 61 6e 65 6f hest instantaneo
3a660 75 73 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 72 us value is.** r
3a670 65 73 65 74 20 62 61 63 6b 20 64 6f 77 6e 20 74 eset back down t
3a680 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 o the current va
3a690 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 lue..**.** See a
3a6a0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 73 74 lso: [sqlite3_st
3a6b0 61 74 75 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c atus()] and [sql
3a6c0 69 74 65 33 5f 73 74 6d 74 5f 73 74 61 74 75 73 ite3_stmt_status
3a6d0 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ()]..*/.SQLITE_A
3a6e0 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 PI SQLITE_EXPERI
3a6f0 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 MENTAL int sqlit
3a700 65 33 5f 64 62 5f 73 74 61 74 75 73 28 73 71 6c e3_db_status(sql
3a710 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 69 ite3*, int op, i
3a720 6e 74 20 2a 70 43 75 72 2c 20 69 6e 74 20 2a 70 nt *pCur, int *p
3a730 48 69 77 74 72 2c 20 69 6e 74 20 72 65 73 65 74 Hiwtr, int reset
3a740 46 6c 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 Flg);../*.** CAP
3a750 49 33 52 45 46 3a 20 53 74 61 74 75 73 20 50 61 I3REF: Status Pa
3a760 72 61 6d 65 74 65 72 73 20 66 6f 72 20 64 61 74 rameters for dat
3a770 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
3a780 73 20 7b 48 31 37 35 32 30 7d 20 3c 48 31 37 35 s {H17520} <H175
3a790 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 00>.** EXPERIMEN
3a7a0 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 TAL.**.** These
3a7b0 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 constants are th
3a7c0 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 e available inte
3a7d0 67 65 72 20 22 76 65 72 62 73 22 20 74 68 61 74 ger "verbs" that
3a7e0 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 can be passed a
3a7f0 73 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 s.** the second
3a800 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
3a810 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 [sqlite3_db_stat
3a820 75 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e us()] interface.
3a830 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 76 65 72 62 73 .**.** New verbs
3a840 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e may be added in
3a850 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
3a860 20 6f 66 20 53 51 4c 69 74 65 2e 20 45 78 69 73 of SQLite. Exis
3a870 74 69 6e 67 20 76 65 72 62 73 0a 2a 2a 20 6d 69 ting verbs.** mi
3a880 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e ght be discontin
3a890 75 65 64 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e ued. Application
3a8a0 73 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 s should check t
3a8b0 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 he return code f
3a8c0 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f rom.** [sqlite3_
3a8d0 64 62 5f 73 74 61 74 75 73 28 29 5d 20 74 6f 20 db_status()] to
3a8e0 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 make sure that t
3a8f0 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 0a he call worked..
3a900 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f ** The [sqlite3_
3a910 64 62 5f 73 74 61 74 75 73 28 29 5d 20 69 6e 74 db_status()] int
3a920 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 erface will retu
3a930 72 6e 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 65 72 rn a non-zero er
3a940 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 69 66 20 61 ror code.** if a
3a950 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 discontinued or
3a960 20 75 6e 73 75 70 70 6f 72 74 65 64 20 76 65 72 unsupported ver
3a970 62 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a b is invoked..**
3a980 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e .** <dl>.** <dt>
3a990 53 51 4c 49 54 45 5f 44 42 53 54 41 54 55 53 5f SQLITE_DBSTATUS_
3a9a0 4c 4f 4f 4b 41 53 49 44 45 5f 55 53 45 44 3c 2f LOOKASIDE_USED</
3a9b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 dt>.** <dd>This
3a9c0 70 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e parameter return
3a9d0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
3a9e0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 lookaside memory
3a9f0 20 73 6c 6f 74 73 20 63 75 72 72 65 6e 74 6c 79 slots currently
3aa00 0a 2a 2a 20 63 68 65 63 6b 65 64 20 6f 75 74 2e .** checked out.
3aa10 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a </dd>.** </dl>.*
3aa20 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
3aa30 5f 44 42 53 54 41 54 55 53 5f 4c 4f 4f 4b 41 53 _DBSTATUS_LOOKAS
3aa40 49 44 45 5f 55 53 45 44 20 20 20 20 20 30 0a 0a IDE_USED 0..
3aa50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
3aa60 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d Prepared Statem
3aa70 65 6e 74 20 53 74 61 74 75 73 20 7b 48 31 37 35 ent Status {H175
3aa80 35 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 50} <S60200>.**
3aa90 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a EXPERIMENTAL.**.
3aaa0 2a 2a 20 45 61 63 68 20 70 72 65 70 61 72 65 64 ** Each prepared
3aab0 20 73 74 61 74 65 6d 65 6e 74 20 6d 61 69 6e 74 statement maint
3aac0 61 69 6e 73 20 76 61 72 69 6f 75 73 0a 2a 2a 20 ains various.**
3aad0 5b 53 51 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 [SQLITE_STMTSTAT
3aae0 55 53 5f 53 4f 52 54 20 7c 20 63 6f 75 6e 74 65 US_SORT | counte
3aaf0 72 73 5d 20 74 68 61 74 20 6d 65 61 73 75 72 65 rs] that measure
3ab00 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f the number.** o
3ab10 66 20 74 69 6d 65 73 20 69 74 20 68 61 73 20 70 f times it has p
3ab20 65 72 66 6f 72 6d 65 64 20 73 70 65 63 69 66 69 erformed specifi
3ab30 63 20 6f 70 65 72 61 74 69 6f 6e 73 2e 20 20 54 c operations. T
3ab40 68 65 73 65 20 63 6f 75 6e 74 65 72 73 20 63 61 hese counters ca
3ab50 6e 0a 2a 2a 20 62 65 20 75 73 65 64 20 74 6f 20 n.** be used to
3ab60 6d 6f 6e 69 74 6f 72 20 74 68 65 20 70 65 72 66 monitor the perf
3ab70 6f 72 6d 61 6e 63 65 20 63 68 61 72 61 63 74 65 ormance characte
3ab80 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 70 ristics of the p
3ab90 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 repared.** state
3aba0 6d 65 6e 74 73 2e 20 20 46 6f 72 20 65 78 61 6d ments. For exam
3abb0 70 6c 65 2c 20 69 66 20 74 68 65 20 6e 75 6d 62 ple, if the numb
3abc0 65 72 20 6f 66 20 74 61 62 6c 65 20 73 74 65 70 er of table step
3abd0 73 20 67 72 65 61 74 6c 79 20 65 78 63 65 65 64 s greatly exceed
3abe0 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 s.** the number
3abf0 6f 66 20 74 61 62 6c 65 20 73 65 61 72 63 68 65 of table searche
3ac00 73 20 6f 72 20 72 65 73 75 6c 74 20 72 6f 77 73 s or result rows
3ac10 2c 20 74 68 61 74 20 77 6f 75 6c 64 20 74 65 6e , that would ten
3ac20 64 20 74 6f 20 69 6e 64 69 63 61 74 65 0a 2a 2a d to indicate.**
3ac30 20 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72 that the prepar
3ac40 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 ed statement is
3ac50 75 73 69 6e 67 20 61 20 66 75 6c 6c 20 74 61 62 using a full tab
3ac60 6c 65 20 73 63 61 6e 20 72 61 74 68 65 72 20 74 le scan rather t
3ac70 68 61 6e 0a 2a 2a 20 61 6e 20 69 6e 64 65 78 2e han.** an index.
3ac80 20 20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e .**.** This in
3ac90 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 terface is used
3aca0 74 6f 20 72 65 74 72 69 65 76 65 20 61 6e 64 20 to retrieve and
3acb0 72 65 73 65 74 20 63 6f 75 6e 74 65 72 20 76 61 reset counter va
3acc0 6c 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 61 20 5b lues from.** a [
3acd0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
3ace0 6e 74 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 nt]. The first
3acf0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 argument is the
3ad00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
3ad10 6e 74 0a 2a 2a 20 6f 62 6a 65 63 74 20 74 6f 20 nt.** object to
3ad20 62 65 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e be interrogated.
3ad30 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 The second arg
3ad40 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 61 6e 20 69 ument.** is an i
3ad50 6e 74 65 67 65 72 20 63 6f 64 65 20 66 6f 72 20 nteger code for
3ad60 61 20 73 70 65 63 69 66 69 63 20 5b 53 51 4c 49 a specific [SQLI
3ad70 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f 53 4f TE_STMTSTATUS_SO
3ad80 52 54 20 7c 20 63 6f 75 6e 74 65 72 5d 0a 2a 2a RT | counter].**
3ad90 20 74 6f 20 62 65 20 69 6e 74 65 72 72 6f 67 61 to be interroga
3ada0 74 65 64 2e 20 0a 2a 2a 20 54 68 65 20 63 75 72 ted. .** The cur
3adb0 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 74 68 rent value of th
3adc0 65 20 72 65 71 75 65 73 74 65 64 20 63 6f 75 6e e requested coun
3add0 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e ter is returned.
3ade0 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 65 74 .** If the reset
3adf0 46 6c 67 20 69 73 20 74 72 75 65 2c 20 74 68 65 Flg is true, the
3ae00 6e 20 74 68 65 20 63 6f 75 6e 74 65 72 20 69 73 n the counter is
3ae10 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 20 61 reset to zero a
3ae20 66 74 65 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 fter this.** int
3ae30 65 72 66 61 63 65 20 63 61 6c 6c 20 72 65 74 75 erface call retu
3ae40 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 rns..**.** See a
3ae50 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 73 74 lso: [sqlite3_st
3ae60 61 74 75 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c atus()] and [sql
3ae70 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 28 29 ite3_db_status()
3ae80 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 ]..*/.SQLITE_API
3ae90 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 SQLITE_EXPERIME
3aea0 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 NTAL int sqlite3
3aeb0 5f 73 74 6d 74 5f 73 74 61 74 75 73 28 73 71 6c _stmt_status(sql
3aec0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
3aed0 6f 70 2c 69 6e 74 20 72 65 73 65 74 46 6c 67 29 op,int resetFlg)
3aee0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
3aef0 46 3a 20 53 74 61 74 75 73 20 50 61 72 61 6d 65 F: Status Parame
3af00 74 65 72 73 20 66 6f 72 20 70 72 65 70 61 72 65 ters for prepare
3af10 64 20 73 74 61 74 65 6d 65 6e 74 73 20 7b 48 31 d statements {H1
3af20 37 35 37 30 7d 20 3c 48 31 37 35 35 30 3e 0a 2a 7570} <H17550>.*
3af30 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a * EXPERIMENTAL.*
3af40 2a 0a 2a 2a 20 54 68 65 73 65 20 70 72 65 70 72 *.** These prepr
3af50 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 20 64 ocessor macros d
3af60 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f efine integer co
3af70 64 65 73 20 74 68 61 74 20 6e 61 6d 65 20 63 6f des that name co
3af80 75 6e 74 65 72 0a 2a 2a 20 76 61 6c 75 65 73 20 unter.** values
3af90 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
3afa0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d the [sqlite3_stm
3afb0 74 5f 73 74 61 74 75 73 28 29 5d 20 69 6e 74 65 t_status()] inte
3afc0 72 66 61 63 65 2e 0a 2a 2a 20 54 68 65 20 6d 65 rface..** The me
3afd0 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 anings of the va
3afe0 72 69 6f 75 73 20 63 6f 75 6e 74 65 72 73 20 61 rious counters a
3aff0 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a re as follows:.*
3b000 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 *.** <dl>.** <dt
3b010 3e 53 51 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 >SQLITE_STMTSTAT
3b020 55 53 5f 46 55 4c 4c 53 43 41 4e 5f 53 54 45 50 US_FULLSCAN_STEP
3b030 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 </dt>.** <dd>Thi
3b040 73 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 s is the number
3b050 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 53 51 of times that SQ
3b060 4c 69 74 65 20 68 61 73 20 73 74 65 70 70 65 64 Lite has stepped
3b070 20 66 6f 72 77 61 72 64 20 69 6e 0a 2a 2a 20 61 forward in.** a
3b080 20 74 61 62 6c 65 20 61 73 20 70 61 72 74 20 6f table as part o
3b090 66 20 61 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 f a full table s
3b0a0 63 61 6e 2e 20 20 4c 61 72 67 65 20 6e 75 6d 62 can. Large numb
3b0b0 65 72 73 20 66 6f 72 20 74 68 69 73 20 63 6f 75 ers for this cou
3b0c0 6e 74 65 72 0a 2a 2a 20 6d 61 79 20 69 6e 64 69 nter.** may indi
3b0d0 63 61 74 65 20 6f 70 70 6f 72 74 75 6e 69 74 69 cate opportuniti
3b0e0 65 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e es for performan
3b0f0 63 65 20 69 6d 70 72 6f 76 65 6d 65 6e 74 20 74 ce improvement t
3b100 68 72 6f 75 67 68 20 0a 2a 2a 20 63 61 72 65 66 hrough .** caref
3b110 75 6c 20 75 73 65 20 6f 66 20 69 6e 64 69 63 65 ul use of indice
3b120 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 s.</dd>.**.** <d
3b130 74 3e 53 51 4c 49 54 45 5f 53 54 4d 54 53 54 41 t>SQLITE_STMTSTA
3b140 54 55 53 5f 53 4f 52 54 3c 2f 64 74 3e 0a 2a 2a TUS_SORT</dt>.**
3b150 20 3c 64 64 3e 54 68 69 73 20 69 73 20 74 68 65 <dd>This is the
3b160 20 6e 75 6d 62 65 72 20 6f 66 20 73 6f 72 74 20 number of sort
3b170 6f 70 65 72 61 74 69 6f 6e 73 20 74 68 61 74 20 operations that
3b180 68 61 76 65 20 6f 63 63 75 72 72 65 64 2e 0a 2a have occurred..*
3b190 2a 20 41 20 6e 6f 6e 2d 7a 65 72 6f 20 76 61 6c * A non-zero val
3b1a0 75 65 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 ue in this count
3b1b0 65 72 20 6d 61 79 20 69 6e 64 69 63 61 74 65 20 er may indicate
3b1c0 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 20 74 an opportunity t
3b1d0 6f 0a 2a 2a 20 69 6d 70 72 6f 76 65 6d 65 6e 74 o.** improvement
3b1e0 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 74 68 72 performance thr
3b1f0 6f 75 67 68 20 63 61 72 65 66 75 6c 20 75 73 65 ough careful use
3b200 20 6f 66 20 69 6e 64 69 63 65 73 2e 3c 2f 64 64 of indices.</dd
3b210 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f >.**.** </dl>.*/
3b220 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3b230 53 54 4d 54 53 54 41 54 55 53 5f 46 55 4c 4c 53 STMTSTATUS_FULLS
3b240 43 41 4e 5f 53 54 45 50 20 20 20 20 20 31 0a 23 CAN_STEP 1.#
3b250 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 define SQLITE_ST
3b260 4d 54 53 54 41 54 55 53 5f 53 4f 52 54 20 20 20 MTSTATUS_SORT
3b270 20 20 20 20 20 20 20 20 20 20 20 32 0a 0a 2f 2a 2../*
3b280 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 75 .** CAPI3REF: Cu
3b290 73 74 6f 6d 20 50 61 67 65 20 43 61 63 68 65 20 stom Page Cache
3b2a0 4f 62 6a 65 63 74 0a 2a 2a 20 45 58 50 45 52 49 Object.** EXPERI
3b2b0 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 MENTAL.**.** The
3b2c0 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 20 sqlite3_pcache
3b2d0 74 79 70 65 20 69 73 20 6f 70 61 71 75 65 2e 20 type is opaque.
3b2e0 20 49 74 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 It is implement
3b2f0 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 6c 75 ed by.** the plu
3b300 67 67 61 62 6c 65 20 6d 6f 64 75 6c 65 2e 20 20 ggable module.
3b310 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 The SQLite core
3b320 68 61 73 20 6e 6f 20 6b 6e 6f 77 6c 65 64 67 65 has no knowledge
3b330 20 6f 66 0a 2a 2a 20 69 74 73 20 73 69 7a 65 20 of.** its size
3b340 6f 72 20 69 6e 74 65 72 6e 61 6c 20 73 74 72 75 or internal stru
3b350 63 74 75 72 65 20 61 6e 64 20 6e 65 76 65 72 20 cture and never
3b360 64 65 61 6c 73 20 77 69 74 68 20 74 68 65 0a 2a deals with the.*
3b370 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 * sqlite3_pcache
3b380 20 6f 62 6a 65 63 74 20 65 78 63 65 70 74 20 62 object except b
3b390 79 20 68 6f 6c 64 69 6e 67 20 61 6e 64 20 70 61 y holding and pa
3b3a0 73 73 69 6e 67 20 70 6f 69 6e 74 65 72 73 0a 2a ssing pointers.*
3b3b0 2a 20 74 6f 20 74 68 65 20 6f 62 6a 65 63 74 2e * to the object.
3b3c0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 5b 73 71 6c 69 .**.** See [sqli
3b3d0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f te3_pcache_metho
3b3e0 64 73 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e ds] for addition
3b3f0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a al information..
3b400 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
3b410 74 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 t sqlite3_pcache
3b420 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 3b sqlite3_pcache;
3b430 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
3b440 3a 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 44 65 : Application De
3b450 66 69 6e 65 64 20 50 61 67 65 20 43 61 63 68 65 fined Page Cache
3b460 2e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b ..** KEYWORDS: {
3b470 70 61 67 65 20 63 61 63 68 65 7d 0a 2a 2a 20 45 page cache}.** E
3b480 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a XPERIMENTAL.**.*
3b490 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 * The [sqlite3_c
3b4a0 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 onfig]([SQLITE_C
3b4b0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 2c 20 2e ONFIG_PCACHE], .
3b4c0 2e 2e 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 ..) interface ca
3b4d0 6e 0a 2a 2a 20 72 65 67 69 73 74 65 72 20 61 6e n.** register an
3b4e0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 70 61 67 alternative pag
3b4f0 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e e cache implemen
3b500 74 61 74 69 6f 6e 20 62 79 20 70 61 73 73 69 6e tation by passin
3b510 67 20 69 6e 20 61 6e 20 0a 2a 2a 20 69 6e 73 74 g in an .** inst
3b520 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 ance of the sqli
3b530 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f te3_pcache_metho
3b540 64 73 20 73 74 72 75 63 74 75 72 65 2e 20 54 68 ds structure. Th
3b550 65 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 74 68 e majority of th
3b560 65 20 0a 2a 2a 20 68 65 61 70 20 6d 65 6d 6f 72 e .** heap memor
3b570 79 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 y used by SQLite
3b580 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 is used by the
3b590 70 61 67 65 20 63 61 63 68 65 20 74 6f 20 63 61 page cache to ca
3b5a0 63 68 65 20 64 61 74 61 20 72 65 61 64 20 0a 2a che data read .*
3b5b0 2a 20 66 72 6f 6d 2c 20 6f 72 20 72 65 61 64 79 * from, or ready
3b5c0 20 74 6f 20 62 65 20 77 72 69 74 74 65 6e 20 74 to be written t
3b5d0 6f 2c 20 74 68 65 20 64 61 74 61 62 61 73 65 20 o, the database
3b5e0 66 69 6c 65 2e 20 42 79 20 69 6d 70 6c 65 6d 65 file. By impleme
3b5f0 6e 74 69 6e 67 20 61 20 0a 2a 2a 20 63 75 73 74 nting a .** cust
3b600 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 75 73 om page cache us
3b610 69 6e 67 20 74 68 69 73 20 41 50 49 2c 20 61 6e ing this API, an
3b620 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e application can
3b630 20 63 6f 6e 74 72 6f 6c 20 6d 6f 72 65 20 0a 2a control more .*
3b640 2a 20 70 72 65 63 69 73 65 6c 79 20 74 68 65 20 * precisely the
3b650 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 amount of memory
3b660 20 63 6f 6e 73 75 6d 65 64 20 62 79 20 53 51 4c consumed by SQL
3b670 69 74 65 2c 20 74 68 65 20 77 61 79 20 69 6e 20 ite, the way in
3b680 77 68 69 63 68 20 0a 2a 2a 20 74 68 61 74 20 6d which .** that m
3b690 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 emory is allocat
3b6a0 65 64 20 61 6e 64 20 72 65 6c 65 61 73 65 64 2c ed and released,
3b6b0 20 61 6e 64 20 74 68 65 20 70 6f 6c 69 63 69 65 and the policie
3b6c0 73 20 75 73 65 64 20 74 6f 20 0a 2a 2a 20 64 65 s used to .** de
3b6d0 74 65 72 6d 69 6e 65 20 65 78 61 63 74 6c 79 20 termine exactly
3b6e0 77 68 69 63 68 20 70 61 72 74 73 20 6f 66 20 61 which parts of a
3b6f0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 database file a
3b700 72 65 20 63 61 63 68 65 64 20 61 6e 64 20 66 6f re cached and fo
3b710 72 20 0a 2a 2a 20 68 6f 77 20 6c 6f 6e 67 2e 0a r .** how long..
3b720 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 6e **.** The conten
3b730 74 73 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 ts of the sqlite
3b740 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 3_pcache_methods
3b750 20 73 74 72 75 63 74 75 72 65 20 61 72 65 20 63 structure are c
3b760 6f 70 69 65 64 20 74 6f 20 61 6e 0a 2a 2a 20 69 opied to an.** i
3b770 6e 74 65 72 6e 61 6c 20 62 75 66 66 65 72 20 62 nternal buffer b
3b780 79 20 53 51 4c 69 74 65 20 77 69 74 68 69 6e 20 y SQLite within
3b790 74 68 65 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c the call to [sql
3b7a0 69 74 65 33 5f 63 6f 6e 66 69 67 5d 2e 20 20 48 ite3_config]. H
3b7b0 65 6e 63 65 0a 2a 2a 20 74 68 65 20 61 70 70 6c ence.** the appl
3b7c0 69 63 61 74 69 6f 6e 20 6d 61 79 20 64 69 73 63 ication may disc
3b7d0 61 72 64 20 74 68 65 20 70 61 72 61 6d 65 74 65 ard the paramete
3b7e0 72 20 61 66 74 65 72 20 74 68 65 20 63 61 6c 6c r after the call
3b7f0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
3b800 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e config()] return
3b810 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e s..**.** The xIn
3b820 69 74 28 29 20 6d 65 74 68 6f 64 20 69 73 20 63 it() method is c
3b830 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 alled once for e
3b840 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ach call to [sql
3b850 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
3b860 29 5d 0a 2a 2a 20 28 75 73 75 61 6c 6c 79 20 6f )].** (usually o
3b870 6e 6c 79 20 6f 6e 63 65 20 64 75 72 69 6e 67 20 nly once during
3b880 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 the lifetime of
3b890 74 68 65 20 70 72 6f 63 65 73 73 29 2e 20 49 74 the process). It
3b8a0 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 61 20 is passed.** a
3b8b0 63 6f 70 79 20 6f 66 20 74 68 65 20 73 71 6c 69 copy of the sqli
3b8c0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f te3_pcache_metho
3b8d0 64 73 2e 70 41 72 67 20 76 61 6c 75 65 2e 20 49 ds.pArg value. I
3b8e0 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f t can be used to
3b8f0 20 73 65 74 0a 2a 2a 20 75 70 20 67 6c 6f 62 61 set.** up globa
3b900 6c 20 73 74 72 75 63 74 75 72 65 73 20 61 6e 64 l structures and
3b910 20 6d 75 74 65 78 65 73 20 72 65 71 75 69 72 65 mutexes require
3b920 64 20 62 79 20 74 68 65 20 63 75 73 74 6f 6d 20 d by the custom
3b930 70 61 67 65 20 63 61 63 68 65 20 0a 2a 2a 20 69 page cache .** i
3b940 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 0a mplementation. .
3b950 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 75 74 64 **.** The xShutd
3b960 6f 77 6e 28 29 20 6d 65 74 68 6f 64 20 69 73 20 own() method is
3b970 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 called from with
3b980 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 in [sqlite3_shut
3b990 64 6f 77 6e 28 29 5d 2c 20 0a 2a 2a 20 69 66 20 down()], .** if
3b9a0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
3b9b0 69 6e 76 6f 6b 65 73 20 74 68 69 73 20 41 50 49 invokes this API
3b9c0 2e 20 49 74 20 63 61 6e 20 62 65 20 75 73 65 64 . It can be used
3b9d0 20 74 6f 20 63 6c 65 61 6e 20 75 70 20 0a 2a 2a to clean up .**
3b9e0 20 61 6e 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 any outstanding
3b9f0 20 72 65 73 6f 75 72 63 65 73 20 62 65 66 6f 72 resources befor
3ba00 65 20 70 72 6f 63 65 73 73 20 73 68 75 74 64 6f e process shutdo
3ba10 77 6e 2c 20 69 66 20 72 65 71 75 69 72 65 64 2e wn, if required.
3ba20 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f .**.** SQLite ho
3ba30 6c 64 73 20 61 20 5b 53 51 4c 49 54 45 5f 4d 55 lds a [SQLITE_MU
3ba40 54 45 58 5f 52 45 43 55 52 53 49 56 45 5d 20 6d TEX_RECURSIVE] m
3ba50 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 utex when it inv
3ba60 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 okes.** the xIni
3ba70 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 t method, so the
3ba80 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 xInit method ne
3ba90 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 ed not be thread
3baa0 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 safe. The.** xS
3bab0 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 hutdown method i
3bac0 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 s only called fr
3bad0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 om [sqlite3_shut
3bae0 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f down()] so it do
3baf0 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 es.** not need t
3bb00 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 o be threadsafe
3bb10 65 69 74 68 65 72 2e 20 20 41 6c 6c 20 6f 74 68 either. All oth
3bb20 65 72 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 er methods must
3bb30 62 65 20 74 68 72 65 61 64 73 61 66 65 0a 2a 2a be threadsafe.**
3bb40 20 69 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65 in multithreade
3bb50 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 2e 0a d applications..
3bb60 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c **.** SQLite wil
3bb70 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 l never invoke x
3bb80 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e Init() more than
3bb90 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e once without an
3bba0 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 intervening.**
3bbb0 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 call to xShutdow
3bbc0 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 n()..**.** The x
3bbd0 43 72 65 61 74 65 28 29 20 6d 65 74 68 6f 64 20 Create() method
3bbe0 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 73 74 is used to const
3bbf0 72 75 63 74 20 61 20 6e 65 77 20 63 61 63 68 65 ruct a new cache
3bc00 20 69 6e 73 74 61 6e 63 65 2e 20 20 53 51 4c 69 instance. SQLi
3bc10 74 65 0a 2a 2a 20 77 69 6c 6c 20 74 79 70 69 63 te.** will typic
3bc20 61 6c 6c 79 20 63 72 65 61 74 65 20 6f 6e 65 20 ally create one
3bc30 63 61 63 68 65 20 69 6e 73 74 61 6e 63 65 20 66 cache instance f
3bc40 6f 72 20 65 61 63 68 20 6f 70 65 6e 20 64 61 74 or each open dat
3bc50 61 62 61 73 65 20 66 69 6c 65 2c 0a 2a 2a 20 74 abase file,.** t
3bc60 68 6f 75 67 68 20 74 68 69 73 20 69 73 20 6e 6f hough this is no
3bc70 74 20 67 75 61 72 61 6e 74 65 65 64 2e 20 54 68 t guaranteed. Th
3bc80 65 0a 2a 2a 20 66 69 72 73 74 20 70 61 72 61 6d e.** first param
3bc90 65 74 65 72 2c 20 73 7a 50 61 67 65 2c 20 69 73 eter, szPage, is
3bca0 20 74 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 the size in byt
3bcb0 65 73 20 6f 66 20 74 68 65 20 70 61 67 65 73 20 es of the pages
3bcc0 74 68 61 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 that must.** be
3bcd0 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 74 68 65 allocated by the
3bce0 20 63 61 63 68 65 2e 20 20 73 7a 50 61 67 65 20 cache. szPage
3bcf0 77 69 6c 6c 20 6e 6f 74 20 62 65 20 61 20 70 6f will not be a po
3bd00 77 65 72 20 6f 66 20 74 77 6f 2e 20 20 73 7a 50 wer of two. szP
3bd10 61 67 65 0a 2a 2a 20 77 69 6c 6c 20 74 68 65 20 age.** will the
3bd20 70 61 67 65 20 73 69 7a 65 20 6f 66 20 74 68 65 page size of the
3bd30 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 database file t
3bd40 68 61 74 20 69 73 20 74 6f 20 62 65 20 63 61 63 hat is to be cac
3bd50 68 65 64 20 70 6c 75 73 20 61 6e 0a 2a 2a 20 69 hed plus an.** i
3bd60 6e 63 72 65 6d 65 6e 74 20 28 68 65 72 65 20 63 ncrement (here c
3bd70 61 6c 6c 65 64 20 22 52 22 29 20 6f 66 20 61 62 alled "R") of ab
3bd80 6f 75 74 20 31 30 30 20 6f 72 20 32 30 30 2e 20 out 100 or 200.
3bd90 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 SQLite will use
3bda0 20 74 68 65 0a 2a 2a 20 65 78 74 72 61 20 52 20 the.** extra R
3bdb0 62 79 74 65 73 20 6f 6e 20 65 61 63 68 20 70 61 bytes on each pa
3bdc0 67 65 20 74 6f 20 73 74 6f 72 65 20 6d 65 74 61 ge to store meta
3bdd0 64 61 74 61 20 61 62 6f 75 74 20 74 68 65 20 75 data about the u
3bde0 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a 20 64 61 74 nderlying.** dat
3bdf0 61 62 61 73 65 20 70 61 67 65 20 6f 6e 20 64 69 abase page on di
3be00 73 6b 2e 20 20 54 68 65 20 76 61 6c 75 65 20 6f sk. The value o
3be10 66 20 52 20 64 65 70 65 6e 64 73 0a 2a 2a 20 6f f R depends.** o
3be20 6e 20 74 68 65 20 53 51 4c 69 74 65 20 76 65 72 n the SQLite ver
3be30 73 69 6f 6e 2c 20 74 68 65 20 74 61 72 67 65 74 sion, the target
3be40 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20 68 platform, and h
3be50 6f 77 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f ow SQLite was co
3be60 6d 70 69 6c 65 64 2e 0a 2a 2a 20 52 20 69 73 20 mpiled..** R is
3be70 63 6f 6e 73 74 61 6e 74 20 66 6f 72 20 61 20 70 constant for a p
3be80 61 72 74 69 63 75 6c 61 72 20 62 75 69 6c 64 20 articular build
3be90 6f 66 20 53 51 4c 69 74 65 2e 20 20 54 68 65 20 of SQLite. The
3bea0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
3beb0 74 6f 0a 2a 2a 20 78 43 72 65 61 74 65 28 29 2c to.** xCreate(),
3bec0 20 62 50 75 72 67 65 61 62 6c 65 2c 20 69 73 20 bPurgeable, is
3bed0 74 72 75 65 20 69 66 20 74 68 65 20 63 61 63 68 true if the cach
3bee0 65 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 20 e being created
3bef0 77 69 6c 6c 0a 2a 2a 20 62 65 20 75 73 65 64 20 will.** be used
3bf00 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 73 to cache databas
3bf10 65 20 70 61 67 65 73 20 6f 66 20 61 20 66 69 6c e pages of a fil
3bf20 65 20 73 74 6f 72 65 64 20 6f 6e 20 64 69 73 6b e stored on disk
3bf30 2c 20 6f 72 0a 2a 2a 20 66 61 6c 73 65 20 69 66 , or.** false if
3bf40 20 69 74 20 69 73 20 75 73 65 64 20 66 6f 72 20 it is used for
3bf50 61 6e 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 an in-memory dat
3bf60 61 62 61 73 65 2e 20 54 68 65 20 63 61 63 68 65 abase. The cache
3bf70 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a implementation.
3bf80 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 ** does not have
3bf90 20 74 6f 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 to do anything
3bfa0 73 70 65 63 69 61 6c 20 62 61 73 65 64 20 77 69 special based wi
3bfb0 74 68 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 th the value of
3bfc0 62 50 75 72 67 65 61 62 6c 65 3b 0a 2a 2a 20 69 bPurgeable;.** i
3bfd0 74 20 69 73 20 70 75 72 65 6c 79 20 61 64 76 69 t is purely advi
3bfe0 73 6f 72 79 2e 20 20 4f 6e 20 61 20 63 61 63 68 sory. On a cach
3bff0 65 20 77 68 65 72 65 20 62 50 75 72 67 65 61 62 e where bPurgeab
3c000 6c 65 20 69 73 20 66 61 6c 73 65 2c 20 53 51 4c le is false, SQL
3c010 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65 ite will.** neve
3c020 72 20 69 6e 76 6f 6b 65 20 78 55 6e 70 69 6e 28 r invoke xUnpin(
3c030 29 20 65 78 63 65 70 74 20 74 6f 20 64 65 6c 69 ) except to deli
3c040 62 65 72 61 74 65 6c 79 20 64 65 6c 65 74 65 20 berately delete
3c050 61 20 70 61 67 65 2e 0a 2a 2a 20 49 6e 20 6f 74 a page..** In ot
3c060 68 65 72 20 77 6f 72 64 73 2c 20 61 20 63 61 63 her words, a cac
3c070 68 65 20 63 72 65 61 74 65 64 20 77 69 74 68 20 he created with
3c080 62 50 75 72 67 65 61 62 6c 65 20 73 65 74 20 74 bPurgeable set t
3c090 6f 20 66 61 6c 73 65 20 77 69 6c 6c 0a 2a 2a 20 o false will.**
3c0a0 6e 65 76 65 72 20 63 6f 6e 74 61 69 6e 20 61 6e never contain an
3c0b0 79 20 75 6e 70 69 6e 6e 65 64 20 70 61 67 65 73 y unpinned pages
3c0c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 43 61 63 ..**.** The xCac
3c0d0 68 65 73 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 hesize() method
3c0e0 6d 61 79 20 62 65 20 63 61 6c 6c 65 64 20 61 74 may be called at
3c0f0 20 61 6e 79 20 74 69 6d 65 20 62 79 20 53 51 4c any time by SQL
3c100 69 74 65 20 74 6f 20 73 65 74 20 74 68 65 0a 2a ite to set the.*
3c110 2a 20 73 75 67 67 65 73 74 65 64 20 6d 61 78 69 * suggested maxi
3c120 6d 75 6d 20 63 61 63 68 65 2d 73 69 7a 65 20 28 mum cache-size (
3c130 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 number of pages
3c140 73 74 6f 72 65 64 20 62 79 29 20 74 68 65 20 63 stored by) the c
3c150 61 63 68 65 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 ache.** instance
3c160 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 passed as the f
3c170 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 54 irst argument. T
3c180 68 69 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 his is the value
3c190 20 63 6f 6e 66 69 67 75 72 65 64 20 75 73 69 6e configured usin
3c1a0 67 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 g.** the SQLite
3c1b0 22 5b 50 52 41 47 4d 41 20 63 61 63 68 65 5f 73 "[PRAGMA cache_s
3c1c0 69 7a 65 5d 22 20 63 6f 6d 6d 61 6e 64 2e 20 41 ize]" command. A
3c1d0 73 20 77 69 74 68 20 74 68 65 20 62 50 75 72 67 s with the bPurg
3c1e0 65 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72 2c eable parameter,
3c1f0 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e .** the implemen
3c200 74 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 72 65 tation is not re
3c210 71 75 69 72 65 64 20 74 6f 20 64 6f 20 61 6e 79 quired to do any
3c220 74 68 69 6e 67 20 77 69 74 68 20 74 68 69 73 0a thing with this.
3c230 2a 2a 20 76 61 6c 75 65 3b 20 69 74 20 69 73 20 ** value; it is
3c240 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a advisory only..*
3c250 2a 0a 2a 2a 20 54 68 65 20 78 50 61 67 65 63 6f *.** The xPageco
3c260 75 6e 74 28 29 20 6d 65 74 68 6f 64 20 73 68 6f unt() method sho
3c270 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 6e uld return the n
3c280 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 63 umber of pages c
3c290 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 73 74 6f 72 urrently.** stor
3c2a0 65 64 20 69 6e 20 74 68 65 20 63 61 63 68 65 2e ed in the cache.
3c2b0 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 78 46 65 74 .** .** The xFet
3c2c0 63 68 28 29 20 6d 65 74 68 6f 64 20 69 73 20 75 ch() method is u
3c2d0 73 65 64 20 74 6f 20 66 65 74 63 68 20 61 20 70 sed to fetch a p
3c2e0 61 67 65 20 61 6e 64 20 72 65 74 75 72 6e 20 61 age and return a
3c2f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e 20 pointer to it.
3c300 0a 2a 2a 20 41 20 27 70 61 67 65 27 2c 20 69 6e .** A 'page', in
3c310 20 74 68 69 73 20 63 6f 6e 74 65 78 74 2c 20 69 this context, i
3c320 73 20 61 20 62 75 66 66 65 72 20 6f 66 20 73 7a s a buffer of sz
3c330 50 61 67 65 20 62 79 74 65 73 20 61 6c 69 67 6e Page bytes align
3c340 65 64 20 61 74 20 61 6e 0a 2a 2a 20 38 2d 62 79 ed at an.** 8-by
3c350 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 54 68 65 te boundary. The
3c360 20 70 61 67 65 20 74 6f 20 62 65 20 66 65 74 63 page to be fetc
3c370 68 65 64 20 69 73 20 64 65 74 65 72 6d 69 6e 65 hed is determine
3c380 64 20 62 79 20 74 68 65 20 6b 65 79 2e 20 54 68 d by the key. Th
3c390 65 0a 2a 2a 20 6d 69 6d 69 6d 75 6d 20 6b 65 79 e.** mimimum key
3c3a0 20 76 61 6c 75 65 20 69 73 20 31 2e 20 41 66 74 value is 1. Aft
3c3b0 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 er it has been r
3c3c0 65 74 72 69 65 76 65 64 20 75 73 69 6e 67 20 78 etrieved using x
3c3d0 46 65 74 63 68 2c 20 74 68 65 20 70 61 67 65 20 Fetch, the page
3c3e0 0a 2a 2a 20 69 73 20 63 6f 6e 73 69 64 65 72 65 .** is considere
3c3f0 64 20 74 6f 20 62 65 20 22 70 69 6e 6e 65 64 22 d to be "pinned"
3c400 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 ..**.** If the r
3c410 65 71 75 65 73 74 65 64 20 70 61 67 65 20 69 73 equested page is
3c420 20 61 6c 72 65 61 64 79 20 69 6e 20 74 68 65 20 already in the
3c430 70 61 67 65 20 63 61 63 68 65 2c 20 74 68 65 6e page cache, then
3c440 20 74 68 65 20 70 61 67 65 20 63 61 63 68 65 0a the page cache.
3c450 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
3c460 6e 20 6d 75 73 74 20 72 65 74 75 72 6e 20 61 20 n must return a
3c470 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 70 pointer to the p
3c480 61 67 65 20 62 75 66 66 65 72 20 77 69 74 68 20 age buffer with
3c490 69 74 73 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 69 its content.** i
3c4a0 6e 74 61 63 74 2e 20 20 49 66 20 74 68 65 20 72 ntact. If the r
3c4b0 65 71 75 65 73 74 65 64 20 70 61 67 65 20 69 73 equested page is
3c4c0 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 69 6e 20 not already in
3c4d0 74 68 65 20 63 61 63 68 65 2c 20 74 68 65 6e 20 the cache, then
3c4e0 74 68 65 0a 2a 2a 20 62 65 68 61 76 69 6f 72 20 the.** behavior
3c4f0 6f 66 20 74 68 65 20 63 61 63 68 65 20 69 6d 70 of the cache imp
3c500 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 64 lementation is d
3c510 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 etermined by the
3c520 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a value of the.**
3c530 20 63 72 65 61 74 65 46 6c 61 67 20 70 61 72 61 createFlag para
3c540 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 meter passed to
3c550 78 46 65 74 63 68 2c 20 61 63 63 6f 72 64 69 6e xFetch, accordin
3c560 67 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 g to the followi
3c570 6e 67 20 74 61 62 6c 65 3a 0a 2a 2a 0a 2a 2a 20 ng table:.**.**
3c580 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 31 20 <table border=1
3c590 77 69 64 74 68 3d 38 35 25 20 61 6c 69 67 6e 3d width=85% align=
3c5a0 63 65 6e 74 65 72 3e 0a 2a 2a 20 3c 74 72 3e 3c center>.** <tr><
3c5b0 74 68 3e 20 63 72 65 61 74 65 46 6c 61 67 20 3c th> createFlag <
3c5c0 74 68 3e 20 42 65 68 61 76 69 6f 75 72 20 77 68 th> Behaviour wh
3c5d0 65 6e 20 70 61 67 65 20 69 73 20 6e 6f 74 20 61 en page is not a
3c5e0 6c 72 65 61 64 79 20 69 6e 20 63 61 63 68 65 0a lready in cache.
3c5f0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 30 20 3c 74 ** <tr><td> 0 <t
3c600 64 3e 20 44 6f 20 6e 6f 74 20 61 6c 6c 6f 63 61 d> Do not alloca
3c610 74 65 20 61 20 6e 65 77 20 70 61 67 65 2e 20 20 te a new page.
3c620 52 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a 20 Return NULL..**
3c630 3c 74 72 3e 3c 74 64 3e 20 31 20 3c 74 64 3e 20 <tr><td> 1 <td>
3c640 41 6c 6c 6f 63 61 74 65 20 61 20 6e 65 77 20 70 Allocate a new p
3c650 61 67 65 20 69 66 20 69 74 20 65 61 73 79 20 61 age if it easy a
3c660 6e 64 20 63 6f 6e 76 65 6e 69 65 6e 74 20 74 6f nd convenient to
3c670 20 64 6f 20 73 6f 2e 0a 2a 2a 20 20 20 20 20 20 do so..**
3c680 20 20 20 20 20 20 20 20 20 20 20 4f 74 68 65 72 Other
3c690 77 69 73 65 20 72 65 74 75 72 6e 20 4e 55 4c 4c wise return NULL
3c6a0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 32 20 ..** <tr><td> 2
3c6b0 3c 74 64 3e 20 4d 61 6b 65 20 65 76 65 72 79 20 <td> Make every
3c6c0 65 66 66 6f 72 74 20 74 6f 20 61 6c 6c 6f 63 61 effort to alloca
3c6d0 74 65 20 61 20 6e 65 77 20 70 61 67 65 2e 20 20 te a new page.
3c6e0 4f 6e 6c 79 20 72 65 74 75 72 6e 0a 2a 2a 20 20 Only return.**
3c6f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 4e N
3c700 55 4c 4c 20 69 66 20 61 6c 6c 6f 63 61 74 69 6e ULL if allocatin
3c710 67 20 61 20 6e 65 77 20 70 61 67 65 20 69 73 20 g a new page is
3c720 65 66 66 65 63 74 69 76 65 6c 79 20 69 6d 70 6f effectively impo
3c730 73 73 69 62 6c 65 2e 0a 2a 2a 20 3c 2f 74 61 62 ssible..** </tab
3c740 6c 65 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 le>.**.** SQLite
3c750 20 77 69 6c 6c 20 6e 6f 72 6d 61 6c 6c 79 20 69 will normally i
3c760 6e 76 6f 6b 65 20 78 46 65 74 63 68 28 29 20 77 nvoke xFetch() w
3c770 69 74 68 20 61 20 63 72 65 61 74 65 46 6c 61 67 ith a createFlag
3c780 20 6f 66 20 30 20 6f 72 20 31 2e 20 20 49 66 0a of 0 or 1. If.
3c790 2a 2a 20 61 20 63 61 6c 6c 20 74 6f 20 78 46 65 ** a call to xFe
3c7a0 74 63 68 28 29 20 77 69 74 68 20 63 72 65 61 74 tch() with creat
3c7b0 65 46 6c 61 67 3d 3d 31 20 72 65 74 75 72 6e 73 eFlag==1 returns
3c7c0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 NULL, then SQLi
3c7d0 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 74 74 65 6d te will.** attem
3c7e0 70 74 20 74 6f 20 75 6e 70 69 6e 20 6f 6e 65 20 pt to unpin one
3c7f0 6f 72 20 6d 6f 72 65 20 63 61 63 68 65 20 70 61 or more cache pa
3c800 67 65 73 20 62 79 20 73 70 69 6c 6c 69 6e 67 20 ges by spilling
3c810 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 0a 2a the content of.*
3c820 2a 20 70 69 6e 6e 65 64 20 70 61 67 65 73 20 74 * pinned pages t
3c830 6f 20 64 69 73 6b 20 61 6e 64 20 73 79 6e 63 68 o disk and synch
3c840 69 6e 67 20 74 68 65 20 6f 70 65 72 61 74 69 6e ing the operatin
3c850 67 20 73 79 73 74 65 6d 20 64 69 73 6b 20 63 61 g system disk ca
3c860 63 68 65 2e 20 41 66 74 65 72 0a 2a 2a 20 61 74 che. After.** at
3c870 74 65 6d 70 74 69 6e 67 20 74 6f 20 75 6e 70 69 tempting to unpi
3c880 6e 20 70 61 67 65 73 2c 20 74 68 65 20 78 46 65 n pages, the xFe
3c890 74 63 68 28 29 20 6d 65 74 68 6f 64 20 77 69 6c tch() method wil
3c8a0 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 61 67 61 l be invoked aga
3c8b0 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 63 72 65 in with.** a cre
3c8c0 61 74 65 46 6c 61 67 20 6f 66 20 32 2e 0a 2a 2a ateFlag of 2..**
3c8d0 0a 2a 2a 20 78 55 6e 70 69 6e 28 29 20 69 73 20 .** xUnpin() is
3c8e0 63 61 6c 6c 65 64 20 62 79 20 53 51 4c 69 74 65 called by SQLite
3c8f0 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 with a pointer
3c900 74 6f 20 61 20 63 75 72 72 65 6e 74 6c 79 20 70 to a currently p
3c910 69 6e 6e 65 64 20 70 61 67 65 0a 2a 2a 20 61 73 inned page.** as
3c920 20 69 74 73 20 73 65 63 6f 6e 64 20 61 72 67 75 its second argu
3c930 6d 65 6e 74 2e 20 49 66 20 74 68 65 20 74 68 69 ment. If the thi
3c940 72 64 20 70 61 72 61 6d 65 74 65 72 2c 20 64 69 rd parameter, di
3c950 73 63 61 72 64 2c 20 69 73 20 6e 6f 6e 2d 7a 65 scard, is non-ze
3c960 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 ro,.** then the
3c970 70 61 67 65 20 73 68 6f 75 6c 64 20 62 65 20 65 page should be e
3c980 76 69 63 74 65 64 20 66 72 6f 6d 20 74 68 65 20 victed from the
3c990 63 61 63 68 65 2e 20 49 6e 20 74 68 69 73 20 63 cache. In this c
3c9a0 61 73 65 20 53 51 4c 69 74 65 20 0a 2a 2a 20 61 ase SQLite .** a
3c9b0 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 ssumes that the
3c9c0 6e 65 78 74 20 74 69 6d 65 20 74 68 65 20 70 61 next time the pa
3c9d0 67 65 20 69 73 20 72 65 74 72 69 65 76 65 64 20 ge is retrieved
3c9e0 66 72 6f 6d 20 74 68 65 20 63 61 63 68 65 20 75 from the cache u
3c9f0 73 69 6e 67 0a 2a 2a 20 74 68 65 20 78 46 65 74 sing.** the xFet
3ca00 63 68 28 29 20 6d 65 74 68 6f 64 2c 20 69 74 20 ch() method, it
3ca10 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e 20 will be zeroed.
3ca20 49 66 20 74 68 65 20 64 69 73 63 61 72 64 20 70 If the discard p
3ca30 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 7a arameter is.** z
3ca40 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 70 61 ero, then the pa
3ca50 67 65 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 ge is considered
3ca60 20 74 6f 20 62 65 20 75 6e 70 69 6e 6e 65 64 2e to be unpinned.
3ca70 20 54 68 65 20 63 61 63 68 65 20 69 6d 70 6c 65 The cache imple
3ca80 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6d 61 79 mentation.** may
3ca90 20 63 68 6f 6f 73 65 20 74 6f 20 65 76 69 63 74 choose to evict
3caa0 20 75 6e 70 69 6e 6e 65 64 20 70 61 67 65 73 20 unpinned pages
3cab0 61 74 20 61 6e 79 20 74 69 6d 65 2e 0a 2a 2a 0a at any time..**.
3cac0 2a 2a 20 54 68 65 20 63 61 63 68 65 20 69 73 20 ** The cache is
3cad0 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 not required to
3cae0 70 65 72 66 6f 72 6d 20 61 6e 79 20 72 65 66 65 perform any refe
3caf0 72 65 6e 63 65 20 63 6f 75 6e 74 69 6e 67 2e 20 rence counting.
3cb00 41 20 73 69 6e 67 6c 65 20 0a 2a 2a 20 63 61 6c A single .** cal
3cb10 6c 20 74 6f 20 78 55 6e 70 69 6e 28 29 20 75 6e l to xUnpin() un
3cb20 70 69 6e 73 20 74 68 65 20 70 61 67 65 20 72 65 pins the page re
3cb30 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 gardless of the
3cb40 6e 75 6d 62 65 72 20 6f 66 20 70 72 69 6f 72 20 number of prior
3cb50 63 61 6c 6c 73 20 0a 2a 2a 20 74 6f 20 78 46 65 calls .** to xFe
3cb60 74 63 68 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 tch()..**.** The
3cb70 20 78 52 65 6b 65 79 28 29 20 6d 65 74 68 6f 64 xRekey() method
3cb80 20 69 73 20 75 73 65 64 20 74 6f 20 63 68 61 6e is used to chan
3cb90 67 65 20 74 68 65 20 6b 65 79 20 76 61 6c 75 65 ge the key value
3cba0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
3cbb0 20 74 68 65 0a 2a 2a 20 70 61 67 65 20 70 61 73 the.** page pas
3cbc0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e sed as the secon
3cbd0 64 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 d argument from
3cbe0 6f 6c 64 4b 65 79 20 74 6f 20 6e 65 77 4b 65 79 oldKey to newKey
3cbf0 2e 20 49 66 20 74 68 65 20 63 61 63 68 65 0a 2a . If the cache.*
3cc00 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6f 6e * previously con
3cc10 74 61 69 6e 73 20 61 6e 20 65 6e 74 72 79 20 61 tains an entry a
3cc20 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 6e ssociated with n
3cc30 65 77 4b 65 79 2c 20 69 74 20 73 68 6f 75 6c 64 ewKey, it should
3cc40 20 62 65 0a 2a 2a 20 64 69 73 63 61 72 64 65 64 be.** discarded
3cc50 2e 20 41 6e 79 20 70 72 69 6f 72 20 63 61 63 68 . Any prior cach
3cc60 65 20 65 6e 74 72 79 20 61 73 73 6f 63 69 61 74 e entry associat
3cc70 65 64 20 77 69 74 68 20 6e 65 77 4b 65 79 20 69 ed with newKey i
3cc80 73 20 67 75 61 72 61 6e 74 65 65 64 20 6e 6f 74 s guaranteed not
3cc90 0a 2a 2a 20 74 6f 20 62 65 20 70 69 6e 6e 65 64 .** to be pinned
3cca0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c ..**.** When SQL
3ccb0 69 74 65 20 63 61 6c 6c 73 20 74 68 65 20 78 54 ite calls the xT
3ccc0 72 75 6e 63 61 74 65 28 29 20 6d 65 74 68 6f 64 runcate() method
3ccd0 2c 20 74 68 65 20 63 61 63 68 65 20 6d 75 73 74 , the cache must
3cce0 20 64 69 73 63 61 72 64 20 61 6c 6c 0a 2a 2a 20 discard all.**
3ccf0 65 78 69 73 74 69 6e 67 20 63 61 63 68 65 20 65 existing cache e
3cd00 6e 74 72 69 65 73 20 77 69 74 68 20 70 61 67 65 ntries with page
3cd10 20 6e 75 6d 62 65 72 73 20 28 6b 65 79 73 29 20 numbers (keys)
3cd20 67 72 65 61 74 65 72 20 74 68 61 6e 20 6f 72 20 greater than or
3cd30 65 71 75 61 6c 0a 2a 2a 20 74 6f 20 74 68 65 20 equal.** to the
3cd40 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 4c 69 value of the iLi
3cd50 6d 69 74 20 70 61 72 61 6d 65 74 65 72 20 70 61 mit parameter pa
3cd60 73 73 65 64 20 74 6f 20 78 54 72 75 6e 63 61 74 ssed to xTruncat
3cd70 65 28 29 2e 20 49 66 20 61 6e 79 0a 2a 2a 20 6f e(). If any.** o
3cd80 66 20 74 68 65 73 65 20 70 61 67 65 73 20 61 72 f these pages ar
3cd90 65 20 70 69 6e 6e 65 64 2c 20 74 68 65 79 20 61 e pinned, they a
3cda0 72 65 20 69 6d 70 6c 69 63 69 74 6c 79 20 75 6e re implicitly un
3cdb0 70 69 6e 6e 65 64 2c 20 6d 65 61 6e 69 6e 67 20 pinned, meaning
3cdc0 74 68 61 74 0a 2a 2a 20 74 68 65 79 20 63 61 6e that.** they can
3cdd0 20 62 65 20 73 61 66 65 6c 79 20 64 69 73 63 61 be safely disca
3cde0 72 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 rded..**.** The
3cdf0 78 44 65 73 74 72 6f 79 28 29 20 6d 65 74 68 6f xDestroy() metho
3ce00 64 20 69 73 20 75 73 65 64 20 74 6f 20 64 65 6c d is used to del
3ce10 65 74 65 20 61 20 63 61 63 68 65 20 61 6c 6c 6f ete a cache allo
3ce20 63 61 74 65 64 20 62 79 20 78 43 72 65 61 74 65 cated by xCreate
3ce30 28 29 2e 0a 2a 2a 20 41 6c 6c 20 72 65 73 6f 75 ()..** All resou
3ce40 72 63 65 73 20 61 73 73 6f 63 69 61 74 65 64 20 rces associated
3ce50 77 69 74 68 20 74 68 65 20 73 70 65 63 69 66 69 with the specifi
3ce60 65 64 20 63 61 63 68 65 20 73 68 6f 75 6c 64 20 ed cache should
3ce70 62 65 20 66 72 65 65 64 2e 20 41 66 74 65 72 0a be freed. After.
3ce80 2a 2a 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 ** calling the x
3ce90 44 65 73 74 72 6f 79 28 29 20 6d 65 74 68 6f 64 Destroy() method
3cea0 2c 20 53 51 4c 69 74 65 20 63 6f 6e 73 69 64 65 , SQLite conside
3ceb0 72 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f rs the [sqlite3_
3cec0 70 63 61 63 68 65 2a 5d 0a 2a 2a 20 68 61 6e 64 pcache*].** hand
3ced0 6c 65 20 69 6e 76 61 6c 69 64 2c 20 61 6e 64 20 le invalid, and
3cee0 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20 69 74 20 will not use it
3cef0 77 69 74 68 20 61 6e 79 20 6f 74 68 65 72 20 73 with any other s
3cf00 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 qlite3_pcache_me
3cf10 74 68 6f 64 73 0a 2a 2a 20 66 75 6e 63 74 69 6f thods.** functio
3cf20 6e 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 ns..*/.typedef s
3cf30 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 70 63 truct sqlite3_pc
3cf40 61 63 68 65 5f 6d 65 74 68 6f 64 73 20 73 71 6c ache_methods sql
3cf50 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 ite3_pcache_meth
3cf60 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 ods;.struct sqli
3cf70 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f te3_pcache_metho
3cf80 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 70 41 72 ds {. void *pAr
3cf90 67 3b 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 g;. int (*xInit
3cfa0 29 28 76 6f 69 64 2a 29 3b 0a 20 20 76 6f 69 64 )(void*);. void
3cfb0 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f (*xShutdown)(vo
3cfc0 69 64 2a 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f id*);. sqlite3_
3cfd0 70 63 61 63 68 65 20 2a 28 2a 78 43 72 65 61 74 pcache *(*xCreat
3cfe0 65 29 28 69 6e 74 20 73 7a 50 61 67 65 2c 20 69 e)(int szPage, i
3cff0 6e 74 20 62 50 75 72 67 65 61 62 6c 65 29 3b 0a nt bPurgeable);.
3d000 20 20 76 6f 69 64 20 28 2a 78 43 61 63 68 65 73 void (*xCaches
3d010 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 70 63 61 ize)(sqlite3_pca
3d020 63 68 65 2a 2c 20 69 6e 74 20 6e 43 61 63 68 65 che*, int nCache
3d030 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 size);. int (*x
3d040 50 61 67 65 63 6f 75 6e 74 29 28 73 71 6c 69 74 Pagecount)(sqlit
3d050 65 33 5f 70 63 61 63 68 65 2a 29 3b 0a 20 20 76 e3_pcache*);. v
3d060 6f 69 64 20 2a 28 2a 78 46 65 74 63 68 29 28 73 oid *(*xFetch)(s
3d070 71 6c 69 74 65 33 5f 70 63 61 63 68 65 2a 2c 20 qlite3_pcache*,
3d080 75 6e 73 69 67 6e 65 64 20 6b 65 79 2c 20 69 6e unsigned key, in
3d090 74 20 63 72 65 61 74 65 46 6c 61 67 29 3b 0a 20 t createFlag);.
3d0a0 20 76 6f 69 64 20 28 2a 78 55 6e 70 69 6e 29 28 void (*xUnpin)(
3d0b0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 2a 2c sqlite3_pcache*,
3d0c0 20 76 6f 69 64 2a 2c 20 69 6e 74 20 64 69 73 63 void*, int disc
3d0d0 61 72 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 ard);. void (*x
3d0e0 52 65 6b 65 79 29 28 73 71 6c 69 74 65 33 5f 70 Rekey)(sqlite3_p
3d0f0 63 61 63 68 65 2a 2c 20 76 6f 69 64 2a 2c 20 75 cache*, void*, u
3d100 6e 73 69 67 6e 65 64 20 6f 6c 64 4b 65 79 2c 20 nsigned oldKey,
3d110 75 6e 73 69 67 6e 65 64 20 6e 65 77 4b 65 79 29 unsigned newKey)
3d120 3b 0a 20 20 76 6f 69 64 20 28 2a 78 54 72 75 6e ;. void (*xTrun
3d130 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 70 63 cate)(sqlite3_pc
3d140 61 63 68 65 2a 2c 20 75 6e 73 69 67 6e 65 64 20 ache*, unsigned
3d150 69 4c 69 6d 69 74 29 3b 0a 20 20 76 6f 69 64 20 iLimit);. void
3d160 28 2a 78 44 65 73 74 72 6f 79 29 28 73 71 6c 69 (*xDestroy)(sqli
3d170 74 65 33 5f 70 63 61 63 68 65 2a 29 3b 0a 7d 3b te3_pcache*);.};
3d180 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
3d190 3a 20 4f 6e 6c 69 6e 65 20 42 61 63 6b 75 70 20 : Online Backup
3d1a0 4f 62 6a 65 63 74 0a 2a 2a 20 45 58 50 45 52 49 Object.** EXPERI
3d1b0 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 MENTAL.**.** The
3d1c0 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 sqlite3_backup
3d1d0 6f 62 6a 65 63 74 20 72 65 63 6f 72 64 73 20 73 object records s
3d1e0 74 61 74 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e tate information
3d1f0 20 61 62 6f 75 74 20 61 6e 20 6f 6e 67 6f 69 6e about an ongoin
3d200 67 0a 2a 2a 20 6f 6e 6c 69 6e 65 20 62 61 63 6b g.** online back
3d210 75 70 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 54 up operation. T
3d220 68 65 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 he sqlite3_backu
3d230 70 20 6f 62 6a 65 63 74 20 69 73 20 63 72 65 61 p object is crea
3d240 74 65 64 20 62 79 0a 2a 2a 20 61 20 63 61 6c 6c ted by.** a call
3d250 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 to [sqlite3_bac
3d260 6b 75 70 5f 69 6e 69 74 28 29 5d 20 61 6e 64 20 kup_init()] and
3d270 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 is destroyed by
3d280 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 a call to.** [sq
3d290 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e lite3_backup_fin
3d2a0 69 73 68 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 ish()]..**.** Se
3d2b0 65 20 41 6c 73 6f 3a 20 5b 55 73 69 6e 67 20 74 e Also: [Using t
3d2c0 68 65 20 53 51 4c 69 74 65 20 4f 6e 6c 69 6e 65 he SQLite Online
3d2d0 20 42 61 63 6b 75 70 20 41 50 49 5d 0a 2a 2f 0a Backup API].*/.
3d2e0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
3d2f0 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 73 71 qlite3_backup sq
3d300 6c 69 74 65 33 5f 62 61 63 6b 75 70 3b 0a 0a 2f lite3_backup;../
3d310 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
3d320 6e 6c 69 6e 65 20 42 61 63 6b 75 70 20 41 50 49 nline Backup API
3d330 2e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 ..** EXPERIMENTA
3d340 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 L.**.** This API
3d350 20 69 73 20 75 73 65 64 20 74 6f 20 6f 76 65 72 is used to over
3d360 77 72 69 74 65 20 74 68 65 20 63 6f 6e 74 65 6e write the conten
3d370 74 73 20 6f 66 20 6f 6e 65 20 64 61 74 61 62 61 ts of one databa
3d380 73 65 20 77 69 74 68 20 74 68 61 74 0a 2a 2a 20 se with that.**
3d390 6f 66 20 61 6e 6f 74 68 65 72 2e 20 49 74 20 69 of another. It i
3d3a0 73 20 75 73 65 66 75 6c 20 65 69 74 68 65 72 20 s useful either
3d3b0 66 6f 72 20 63 72 65 61 74 69 6e 67 20 62 61 63 for creating bac
3d3c0 6b 75 70 73 20 6f 66 20 64 61 74 61 62 61 73 65 kups of database
3d3d0 73 20 6f 72 0a 2a 2a 20 66 6f 72 20 63 6f 70 79 s or.** for copy
3d3e0 69 6e 67 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 ing in-memory da
3d3f0 74 61 62 61 73 65 73 20 74 6f 20 6f 72 20 66 72 tabases to or fr
3d400 6f 6d 20 70 65 72 73 69 73 74 65 6e 74 20 66 69 om persistent fi
3d410 6c 65 73 2e 20 0a 2a 2a 0a 2a 2a 20 53 65 65 20 les. .**.** See
3d420 41 6c 73 6f 3a 20 5b 55 73 69 6e 67 20 74 68 65 Also: [Using the
3d430 20 53 51 4c 69 74 65 20 4f 6e 6c 69 6e 65 20 42 SQLite Online B
3d440 61 63 6b 75 70 20 41 50 49 5d 0a 2a 2a 0a 2a 2a ackup API].**.**
3d450 20 45 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 Exclusive acces
3d460 73 20 69 73 20 72 65 71 75 69 72 65 64 20 74 6f s is required to
3d470 20 74 68 65 20 64 65 73 74 69 6e 61 74 69 6f 6e the destination
3d480 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 74 68 database for th
3d490 65 20 0a 2a 2a 20 64 75 72 61 74 69 6f 6e 20 6f e .** duration o
3d4a0 66 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 2e f the operation.
3d4b0 20 48 6f 77 65 76 65 72 20 74 68 65 20 73 6f 75 However the sou
3d4c0 72 63 65 20 64 61 74 61 62 61 73 65 20 69 73 20 rce database is
3d4d0 6f 6e 6c 79 0a 2a 2a 20 72 65 61 64 2d 6c 6f 63 only.** read-loc
3d4e0 6b 65 64 20 77 68 69 6c 65 20 69 74 20 69 73 20 ked while it is
3d4f0 61 63 74 75 61 6c 6c 79 20 62 65 69 6e 67 20 72 actually being r
3d500 65 61 64 2c 20 69 74 20 69 73 20 6e 6f 74 20 6c ead, it is not l
3d510 6f 63 6b 65 64 0a 2a 2a 20 63 6f 6e 74 69 6e 75 ocked.** continu
3d520 6f 75 73 6c 79 20 66 6f 72 20 74 68 65 20 65 6e ously for the en
3d530 74 69 72 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 tire operation.
3d540 54 68 75 73 2c 20 74 68 65 20 62 61 63 6b 75 70 Thus, the backup
3d550 20 6d 61 79 20 62 65 0a 2a 2a 20 70 65 72 66 6f may be.** perfo
3d560 72 6d 65 64 20 6f 6e 20 61 20 6c 69 76 65 20 64 rmed on a live d
3d570 61 74 61 62 61 73 65 20 77 69 74 68 6f 75 74 20 atabase without
3d580 70 72 65 76 65 6e 74 69 6e 67 20 6f 74 68 65 72 preventing other
3d590 20 75 73 65 72 73 20 66 72 6f 6d 0a 2a 2a 20 77 users from.** w
3d5a0 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20 64 61 riting to the da
3d5b0 74 61 62 61 73 65 20 66 6f 72 20 61 6e 20 65 78 tabase for an ex
3d5c0 74 65 6e 64 65 64 20 70 65 72 69 6f 64 20 6f 66 tended period of
3d5d0 20 74 69 6d 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 6f time..** .** To
3d5e0 20 70 65 72 66 6f 72 6d 20 61 20 62 61 63 6b 75 perform a backu
3d5f0 70 20 6f 70 65 72 61 74 69 6f 6e 3a 20 0a 2a 2a p operation: .**
3d600 20 20 20 3c 6f 6c 3e 0a 2a 2a 20 20 20 20 20 3c <ol>.** <
3d610 6c 69 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 62 61 li><b>sqlite3_ba
3d620 63 6b 75 70 5f 69 6e 69 74 28 29 3c 2f 62 3e 20 ckup_init()</b>
3d630 69 73 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 74 is called once t
3d640 6f 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 o initialize the
3d650 0a 2a 2a 20 20 20 20 20 20 20 20 20 62 61 63 6b .** back
3d660 75 70 2c 20 0a 2a 2a 20 20 20 20 20 3c 6c 69 3e up, .** <li>
3d670 3c 62 3e 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 <b>sqlite3_backu
3d680 70 5f 73 74 65 70 28 29 3c 2f 62 3e 20 69 73 20 p_step()</b> is
3d690 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f called one or mo
3d6a0 72 65 20 74 69 6d 65 73 20 74 6f 20 74 72 61 6e re times to tran
3d6b0 73 66 65 72 20 0a 2a 2a 20 20 20 20 20 20 20 20 sfer .**
3d6c0 20 74 68 65 20 64 61 74 61 20 62 65 74 77 65 65 the data betwee
3d6d0 6e 20 74 68 65 20 74 77 6f 20 64 61 74 61 62 61 n the two databa
3d6e0 73 65 73 2c 20 61 6e 64 20 66 69 6e 61 6c 6c 79 ses, and finally
3d6f0 0a 2a 2a 20 20 20 20 20 3c 6c 69 3e 3c 62 3e 73 .** <li><b>s
3d700 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 qlite3_backup_fi
3d710 6e 69 73 68 28 29 3c 2f 62 3e 20 69 73 20 63 61 nish()</b> is ca
3d720 6c 6c 65 64 20 74 6f 20 72 65 6c 65 61 73 65 20 lled to release
3d730 61 6c 6c 20 72 65 73 6f 75 72 63 65 73 20 0a 2a all resources .*
3d740 2a 20 20 20 20 20 20 20 20 20 61 73 73 6f 63 69 * associ
3d750 61 74 65 64 20 77 69 74 68 20 74 68 65 20 62 61 ated with the ba
3d760 63 6b 75 70 20 6f 70 65 72 61 74 69 6f 6e 2e 20 ckup operation.
3d770 0a 2a 2a 20 20 20 3c 2f 6f 6c 3e 0a 2a 2a 20 54 .** </ol>.** T
3d780 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 65 here should be e
3d790 78 61 63 74 6c 79 20 6f 6e 65 20 63 61 6c 6c 20 xactly one call
3d7a0 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 to sqlite3_backu
3d7b0 70 5f 66 69 6e 69 73 68 28 29 20 66 6f 72 20 65 p_finish() for e
3d7c0 61 63 68 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 ach.** successfu
3d7d0 6c 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 l call to sqlite
3d7e0 33 5f 62 61 63 6b 75 70 5f 69 6e 69 74 28 29 2e 3_backup_init().
3d7f0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 73 71 6c 69 74 65 .**.** <b>sqlite
3d800 33 5f 62 61 63 6b 75 70 5f 69 6e 69 74 28 29 3c 3_backup_init()<
3d810 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 /b>.**.** The fi
3d820 72 73 74 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 rst two argument
3d830 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c s passed to [sql
3d840 69 74 65 33 5f 62 61 63 6b 75 70 5f 69 6e 69 74 ite3_backup_init
3d850 28 29 5d 20 61 72 65 20 74 68 65 20 64 61 74 61 ()] are the data
3d860 62 61 73 65 0a 2a 2a 20 68 61 6e 64 6c 65 20 61 base.** handle a
3d870 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
3d880 68 65 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 he destination d
3d890 61 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20 atabase and the
3d8a0 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 0a 2a database name .*
3d8b0 2a 20 75 73 65 64 20 74 6f 20 61 74 74 61 63 68 * used to attach
3d8c0 20 74 68 65 20 64 65 73 74 69 6e 61 74 69 6f 6e the destination
3d8d0 20 64 61 74 61 62 61 73 65 20 74 6f 20 74 68 65 database to the
3d8e0 20 68 61 6e 64 6c 65 2e 20 54 68 65 20 64 61 74 handle. The dat
3d8f0 61 62 61 73 65 20 6e 61 6d 65 0a 2a 2a 20 69 73 abase name.** is
3d900 20 22 6d 61 69 6e 22 20 66 6f 72 20 74 68 65 20 "main" for the
3d910 6d 61 69 6e 20 64 61 74 61 62 61 73 65 2c 20 22 main database, "
3d920 74 65 6d 70 22 20 66 6f 72 20 74 68 65 20 74 65 temp" for the te
3d930 6d 70 6f 72 61 72 79 20 64 61 74 61 62 61 73 65 mporary database
3d940 2c 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 , or.** the name
3d950 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61 specified as pa
3d960 72 74 20 6f 66 20 74 68 65 20 5b 41 54 54 41 43 rt of the [ATTAC
3d970 48 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 66 20 H] statement if
3d980 74 68 65 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 the destination
3d990 69 73 0a 2a 2a 20 61 6e 20 61 74 74 61 63 68 65 is.** an attache
3d9a0 64 20 64 61 74 61 62 61 73 65 2e 20 54 68 65 20 d database. The
3d9b0 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 third and fourth
3d9c0 20 61 72 67 75 6d 65 6e 74 73 20 70 61 73 73 65 arguments passe
3d9d0 64 20 74 6f 20 0a 2a 2a 20 73 71 6c 69 74 65 33 d to .** sqlite3
3d9e0 5f 62 61 63 6b 75 70 5f 69 6e 69 74 28 29 20 69 _backup_init() i
3d9f0 64 65 6e 74 69 66 79 20 74 68 65 20 5b 64 61 74 dentify the [dat
3da00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
3da10 5d 0a 2a 2a 20 61 6e 64 20 64 61 74 61 62 61 73 ].** and databas
3da20 65 20 6e 61 6d 65 20 75 73 65 64 0a 2a 2a 20 74 e name used.** t
3da30 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 6f 75 o access the sou
3da40 72 63 65 20 64 61 74 61 62 61 73 65 2e 20 54 68 rce database. Th
3da50 65 20 76 61 6c 75 65 73 20 70 61 73 73 65 64 20 e values passed
3da60 66 6f 72 20 74 68 65 20 73 6f 75 72 63 65 20 61 for the source a
3da70 6e 64 20 0a 2a 2a 20 64 65 73 74 69 6e 61 74 69 nd .** destinati
3da80 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e on [database con
3da90 6e 65 63 74 69 6f 6e 5d 20 70 61 72 61 6d 65 74 nection] paramet
3daa0 65 72 73 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 ers must not be
3dab0 74 68 65 20 73 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 the same..**.**
3dac0 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 If an error occu
3dad0 72 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 rs within sqlite
3dae0 33 5f 62 61 63 6b 75 70 5f 69 6e 69 74 28 29 2c 3_backup_init(),
3daf0 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 then NULL is re
3db00 74 75 72 6e 65 64 0a 2a 2a 20 61 6e 64 20 61 6e turned.** and an
3db10 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 error code and
3db20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 77 72 error message wr
3db30 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 5b itten into the [
3db40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
3db50 69 6f 6e 5d 20 0a 2a 2a 20 70 61 73 73 65 64 20 ion] .** passed
3db60 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 as the first arg
3db70 75 6d 65 6e 74 2e 20 54 68 65 79 20 6d 61 79 20 ument. They may
3db80 62 65 20 72 65 74 72 69 65 76 65 64 20 75 73 69 be retrieved usi
3db90 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 ng the.** [sqlit
3dba0 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b e3_errcode()], [
3dbb0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 sqlite3_errmsg()
3dbc0 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ], and [sqlite3_
3dbd0 65 72 72 6d 73 67 31 36 28 29 5d 20 66 75 6e 63 errmsg16()] func
3dbe0 74 69 6f 6e 73 2e 0a 2a 2a 20 4f 74 68 65 72 77 tions..** Otherw
3dbf0 69 73 65 2c 20 69 66 20 73 75 63 63 65 73 73 66 ise, if successf
3dc00 75 6c 2c 20 61 20 70 6f 69 6e 74 65 72 20 74 6f ul, a pointer to
3dc10 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 an [sqlite3_bac
3dc20 6b 75 70 5d 20 6f 62 6a 65 63 74 20 69 73 0a 2a kup] object is.*
3dc30 2a 20 72 65 74 75 72 6e 65 64 2e 20 54 68 69 73 * returned. This
3dc40 20 70 6f 69 6e 74 65 72 20 6d 61 79 20 62 65 20 pointer may be
3dc50 75 73 65 64 20 77 69 74 68 20 74 68 65 20 73 71 used with the sq
3dc60 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 lite3_backup_ste
3dc70 70 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 p() and.** sqlit
3dc80 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 e3_backup_finish
3dc90 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 () functions to
3dca0 70 65 72 66 6f 72 6d 20 74 68 65 20 73 70 65 63 perform the spec
3dcb0 69 66 69 65 64 20 62 61 63 6b 75 70 20 0a 2a 2a ified backup .**
3dcc0 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a operation..**.*
3dcd0 2a 20 3c 62 3e 73 71 6c 69 74 65 33 5f 62 61 63 * <b>sqlite3_bac
3dce0 6b 75 70 5f 73 74 65 70 28 29 3c 2f 62 3e 0a 2a kup_step()</b>.*
3dcf0 2a 0a 2a 2a 20 46 75 6e 63 74 69 6f 6e 20 5b 73 *.** Function [s
3dd00 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 qlite3_backup_st
3dd10 65 70 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f ep()] is used to
3dd20 20 63 6f 70 79 20 75 70 20 74 6f 20 6e 50 61 67 copy up to nPag
3dd30 65 20 70 61 67 65 73 20 62 65 74 77 65 65 6e 20 e pages between
3dd40 0a 2a 2a 20 74 68 65 20 73 6f 75 72 63 65 20 61 .** the source a
3dd50 6e 64 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 nd destination d
3dd60 61 74 61 62 61 73 65 73 2c 20 77 68 65 72 65 20 atabases, where
3dd70 6e 50 61 67 65 20 69 73 20 74 68 65 20 76 61 6c nPage is the val
3dd80 75 65 20 6f 66 20 74 68 65 20 0a 2a 2a 20 73 65 ue of the .** se
3dd90 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 70 cond parameter p
3dda0 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 assed to sqlite3
3ddb0 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 2e 20 _backup_step().
3ddc0 49 66 20 6e 50 61 67 65 20 69 73 20 61 20 6e 65 If nPage is a ne
3ddd0 67 61 74 69 76 65 0a 2a 2a 20 76 61 6c 75 65 2c gative.** value,
3dde0 20 61 6c 6c 20 72 65 6d 61 69 6e 69 6e 67 20 73 all remaining s
3ddf0 6f 75 72 63 65 20 70 61 67 65 73 20 61 72 65 20 ource pages are
3de00 63 6f 70 69 65 64 2e 20 49 66 20 74 68 65 20 72 copied. If the r
3de10 65 71 75 69 72 65 64 20 70 61 67 65 73 20 61 72 equired pages ar
3de20 65 20 0a 2a 2a 20 73 75 63 63 65 73 66 75 6c 6c e .** succesfull
3de30 79 20 63 6f 70 69 65 64 2c 20 62 75 74 20 74 68 y copied, but th
3de40 65 72 65 20 61 72 65 20 73 74 69 6c 6c 20 6d 6f ere are still mo
3de50 72 65 20 70 61 67 65 73 20 74 6f 20 63 6f 70 79 re pages to copy
3de60 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 before the .**
3de70 62 61 63 6b 75 70 20 69 73 20 63 6f 6d 70 6c 65 backup is comple
3de80 74 65 2c 20 69 74 20 72 65 74 75 72 6e 73 20 5b te, it returns [
3de90 53 51 4c 49 54 45 5f 4f 4b 5d 2e 20 49 66 20 6e SQLITE_OK]. If n
3dea0 6f 20 65 72 72 6f 72 20 6f 63 63 75 72 65 64 20 o error occured
3deb0 61 6e 64 20 74 68 65 72 65 20 0a 2a 2a 20 61 72 and there .** ar
3dec0 65 20 6e 6f 20 6d 6f 72 65 20 70 61 67 65 73 20 e no more pages
3ded0 74 6f 20 63 6f 70 79 2c 20 74 68 65 6e 20 5b 53 to copy, then [S
3dee0 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 69 73 20 72 QLITE_DONE] is r
3def0 65 74 75 72 6e 65 64 2e 20 49 66 20 61 6e 20 65 eturned. If an e
3df00 72 72 6f 72 20 0a 2a 2a 20 6f 63 63 75 72 73 2c rror .** occurs,
3df10 20 74 68 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 then an SQLite
3df20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 error code is re
3df30 74 75 72 6e 65 64 2e 20 41 73 20 77 65 6c 6c 20 turned. As well
3df40 61 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 as [SQLITE_OK] a
3df50 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f nd.** [SQLITE_DO
3df60 4e 45 5d 2c 20 61 20 63 61 6c 6c 20 74 6f 20 73 NE], a call to s
3df70 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 qlite3_backup_st
3df80 65 70 28 29 20 6d 61 79 20 72 65 74 75 72 6e 20 ep() may return
3df90 5b 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 [SQLITE_READONLY
3dfa0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f ],.** [SQLITE_NO
3dfb0 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 MEM], [SQLITE_BU
3dfc0 53 59 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 SY], [SQLITE_LOC
3dfd0 4b 45 44 5d 2c 20 6f 72 20 61 6e 0a 2a 2a 20 5b KED], or an.** [
3dfe0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 SQLITE_IOERR_ACC
3dff0 45 53 53 20 7c 20 53 51 4c 49 54 45 5f 49 4f 45 ESS | SQLITE_IOE
3e000 52 52 5f 58 58 58 5d 20 65 78 74 65 6e 64 65 64 RR_XXX] extended
3e010 20 65 72 72 6f 72 20 63 6f 64 65 2e 0a 2a 2a 0a error code..**.
3e020 2a 2a 20 41 73 20 77 65 6c 6c 20 61 73 20 74 68 ** As well as th
3e030 65 20 63 61 73 65 20 77 68 65 72 65 20 74 68 65 e case where the
3e040 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 destination dat
3e050 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 6f abase file was o
3e060 70 65 6e 65 64 20 66 6f 72 0a 2a 2a 20 72 65 61 pened for.** rea
3e070 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2c 20 73 d-only access, s
3e080 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 qlite3_backup_st
3e090 65 70 28 29 20 6d 61 79 20 72 65 74 75 72 6e 20 ep() may return
3e0a0 5b 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 [SQLITE_READONLY
3e0b0 5d 20 69 66 0a 2a 2a 20 74 68 65 20 64 65 73 74 ] if.** the dest
3e0c0 69 6e 61 74 69 6f 6e 20 69 73 20 61 6e 20 69 6e ination is an in
3e0d0 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 -memory database
3e0e0 20 77 69 74 68 20 61 20 64 69 66 66 65 72 65 6e with a differen
3e0f0 74 20 70 61 67 65 20 73 69 7a 65 0a 2a 2a 20 66 t page size.** f
3e100 72 6f 6d 20 74 68 65 20 73 6f 75 72 63 65 20 64 rom the source d
3e110 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 49 atabase..**.** I
3e120 66 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 f sqlite3_backup
3e130 5f 73 74 65 70 28 29 20 63 61 6e 6e 6f 74 20 6f _step() cannot o
3e140 62 74 61 69 6e 20 61 20 72 65 71 75 69 72 65 64 btain a required
3e150 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 6c 6f 63 file-system loc
3e160 6b 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 5b k, then.** the [
3e170 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e sqlite3_busy_han
3e180 64 6c 65 72 20 7c 20 62 75 73 79 2d 68 61 6e 64 dler | busy-hand
3e190 6c 65 72 20 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2a ler function].**
3e1a0 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 66 20 is invoked (if
3e1b0 6f 6e 65 20 69 73 20 73 70 65 63 69 66 69 65 64 one is specified
3e1c0 29 2e 20 49 66 20 74 68 65 20 0a 2a 2a 20 62 75 ). If the .** bu
3e1d0 73 79 2d 68 61 6e 64 6c 65 72 20 72 65 74 75 72 sy-handler retur
3e1e0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 62 65 66 6f ns non-zero befo
3e1f0 72 65 20 74 68 65 20 6c 6f 63 6b 20 69 73 20 61 re the lock is a
3e200 76 61 69 6c 61 62 6c 65 2c 20 74 68 65 6e 20 0a vailable, then .
3e210 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d ** [SQLITE_BUSY]
3e220 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 is returned to
3e230 74 68 65 20 63 61 6c 6c 65 72 2e 20 49 6e 20 74 the caller. In t
3e240 68 69 73 20 63 61 73 65 20 74 68 65 20 63 61 6c his case the cal
3e250 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f l to.** sqlite3_
3e260 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 63 61 backup_step() ca
3e270 6e 20 62 65 20 72 65 74 72 69 65 64 20 6c 61 74 n be retried lat
3e280 65 72 2e 20 49 66 20 74 68 65 20 73 6f 75 72 63 er. If the sourc
3e290 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 e.** [database c
3e2a0 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 73 onnection].** is
3e2b0 20 62 65 69 6e 67 20 75 73 65 64 20 74 6f 20 77 being used to w
3e2c0 72 69 74 65 20 74 6f 20 74 68 65 20 73 6f 75 72 rite to the sour
3e2d0 63 65 20 64 61 74 61 62 61 73 65 20 77 68 65 6e ce database when
3e2e0 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f sqlite3_backup_
3e2f0 73 74 65 70 28 29 0a 2a 2a 20 69 73 20 63 61 6c step().** is cal
3e300 6c 65 64 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 led, then [SQLIT
3e310 45 5f 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 E_LOCKED] is ret
3e320 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c urned immediatel
3e330 79 2e 20 41 67 61 69 6e 2c 20 69 6e 20 74 68 69 y. Again, in thi
3e340 73 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 63 61 s.** case the ca
3e350 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 ll to sqlite3_ba
3e360 63 6b 75 70 5f 73 74 65 70 28 29 20 63 61 6e 20 ckup_step() can
3e370 62 65 20 72 65 74 72 69 65 64 20 6c 61 74 65 72 be retried later
3e380 20 6f 6e 2e 20 49 66 0a 2a 2a 20 5b 53 51 4c 49 on. If.** [SQLI
3e390 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 TE_IOERR_ACCESS
3e3a0 7c 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 58 | SQLITE_IOERR_X
3e3b0 58 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d XX], [SQLITE_NOM
3e3c0 45 4d 5d 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 EM], or.** [SQLI
3e3d0 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 20 69 73 20 TE_READONLY] is
3e3e0 72 65 74 75 72 6e 65 64 2c 20 74 68 65 6e 20 0a returned, then .
3e3f0 2a 2a 20 74 68 65 72 65 20 69 73 20 6e 6f 20 70 ** there is no p
3e400 6f 69 6e 74 20 69 6e 20 72 65 74 72 79 69 6e 67 oint in retrying
3e410 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c the call to sql
3e420 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 ite3_backup_step
3e430 28 29 2e 20 54 68 65 73 65 20 0a 2a 2a 20 65 72 (). These .** er
3e440 72 6f 72 73 20 61 72 65 20 63 6f 6e 73 69 64 65 rors are conside
3e450 72 65 64 20 66 61 74 61 6c 2e 20 41 74 20 74 68 red fatal. At th
3e460 69 73 20 70 6f 69 6e 74 20 74 68 65 20 61 70 70 is point the app
3e470 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 61 63 lication must ac
3e480 63 65 70 74 20 0a 2a 2a 20 74 68 61 74 20 74 68 cept .** that th
3e490 65 20 62 61 63 6b 75 70 20 6f 70 65 72 61 74 69 e backup operati
3e4a0 6f 6e 20 68 61 73 20 66 61 69 6c 65 64 20 61 6e on has failed an
3e4b0 64 20 70 61 73 73 20 74 68 65 20 62 61 63 6b 75 d pass the backu
3e4c0 70 20 6f 70 65 72 61 74 69 6f 6e 20 68 61 6e 64 p operation hand
3e4d0 6c 65 20 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 le .** to the sq
3e4e0 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e lite3_backup_fin
3e4f0 69 73 68 28 29 20 74 6f 20 72 65 6c 65 61 73 65 ish() to release
3e500 20 61 73 73 6f 63 69 61 74 65 64 20 72 65 73 6f associated reso
3e510 75 72 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 46 6f 6c urces..**.** Fol
3e520 6c 6f 77 69 6e 67 20 74 68 65 20 66 69 72 73 74 lowing the first
3e530 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
3e540 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 2c 20 _backup_step(),
3e550 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 an exclusive loc
3e560 6b 20 69 73 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 k is.** obtained
3e570 20 6f 6e 20 74 68 65 20 64 65 73 74 69 6e 61 74 on the destinat
3e580 69 6f 6e 20 66 69 6c 65 2e 20 49 74 20 69 73 20 ion file. It is
3e590 6e 6f 74 20 72 65 6c 65 61 73 65 64 20 75 6e 74 not released unt
3e5a0 69 6c 20 65 69 74 68 65 72 20 0a 2a 2a 20 73 71 il either .** sq
3e5b0 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e lite3_backup_fin
3e5c0 69 73 68 28 29 20 69 73 20 63 61 6c 6c 65 64 20 ish() is called
3e5d0 6f 72 20 74 68 65 20 62 61 63 6b 75 70 20 6f 70 or the backup op
3e5e0 65 72 61 74 69 6f 6e 20 69 73 20 63 6f 6d 70 6c eration is compl
3e5f0 65 74 65 20 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 ete .** and sqli
3e600 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 te3_backup_step(
3e610 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 ) returns [SQLIT
3e620 45 5f 44 4f 4e 45 5d 2e 20 41 64 64 69 74 69 6f E_DONE]. Additio
3e630 6e 61 6c 6c 79 2c 20 65 61 63 68 20 74 69 6d 65 nally, each time
3e640 20 0a 2a 2a 20 61 20 63 61 6c 6c 20 74 6f 20 73 .** a call to s
3e650 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 qlite3_backup_st
3e660 65 70 28 29 20 69 73 20 6d 61 64 65 20 61 20 5b ep() is made a [
3e670 73 68 61 72 65 64 20 6c 6f 63 6b 5d 20 69 73 20 shared lock] is
3e680 6f 62 74 61 69 6e 65 64 20 6f 6e 0a 2a 2a 20 74 obtained on.** t
3e690 68 65 20 73 6f 75 72 63 65 20 64 61 74 61 62 61 he source databa
3e6a0 73 65 20 66 69 6c 65 2e 20 54 68 69 73 20 6c 6f se file. This lo
3e6b0 63 6b 20 69 73 20 72 65 6c 65 61 73 65 64 20 62 ck is released b
3e6c0 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 73 71 6c efore the.** sql
3e6d0 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 ite3_backup_step
3e6e0 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e () call returns.
3e6f0 20 42 65 63 61 75 73 65 20 74 68 65 20 73 6f 75 Because the sou
3e700 72 63 65 20 64 61 74 61 62 61 73 65 20 69 73 20 rce database is
3e710 6e 6f 74 0a 2a 2a 20 6c 6f 63 6b 65 64 20 62 65 not.** locked be
3e720 74 77 65 65 6e 20 63 61 6c 6c 73 20 74 6f 20 73 tween calls to s
3e730 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 qlite3_backup_st
3e740 65 70 28 29 2c 20 69 74 20 6d 61 79 20 62 65 20 ep(), it may be
3e750 6d 6f 64 69 66 69 65 64 20 6d 69 64 2d 77 61 79 modified mid-way
3e760 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 .** through the
3e770 62 61 63 6b 75 70 20 70 72 6f 63 65 64 75 72 65 backup procedure
3e780 2e 20 49 66 20 74 68 65 20 73 6f 75 72 63 65 20 . If the source
3e790 64 61 74 61 62 61 73 65 20 69 73 20 6d 6f 64 69 database is modi
3e7a0 66 69 65 64 20 62 79 20 61 6e 0a 2a 2a 20 65 78 fied by an.** ex
3e7b0 74 65 72 6e 61 6c 20 70 72 6f 63 65 73 73 20 6f ternal process o
3e7c0 72 20 76 69 61 20 61 20 64 61 74 61 62 61 73 65 r via a database
3e7d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 74 68 65 connection othe
3e7e0 72 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 62 r than the one b
3e7f0 65 69 6e 67 0a 2a 2a 20 75 73 65 64 20 62 79 20 eing.** used by
3e800 74 68 65 20 62 61 63 6b 75 70 20 6f 70 65 72 61 the backup opera
3e810 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 62 tion, then the b
3e820 61 63 6b 75 70 20 77 69 6c 6c 20 62 65 20 74 72 ackup will be tr
3e830 61 6e 73 70 61 72 65 6e 74 6c 79 0a 2a 2a 20 72 ansparently.** r
3e840 65 73 74 61 72 74 65 64 20 62 79 20 74 68 65 20 estarted by the
3e850 6e 65 78 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c next call to sql
3e860 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 ite3_backup_step
3e870 28 29 2e 20 49 66 20 74 68 65 20 73 6f 75 72 63 (). If the sourc
3e880 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 e .** database i
3e890 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68 s modified by th
3e8a0 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 e using the same
3e8b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
3e8c0 74 69 6f 6e 20 61 73 20 69 73 20 75 73 65 64 0a tion as is used.
3e8d0 2a 2a 20 62 79 20 74 68 65 20 62 61 63 6b 75 70 ** by the backup
3e8e0 20 6f 70 65 72 61 74 69 6f 6e 2c 20 74 68 65 6e operation, then
3e8f0 20 74 68 65 20 62 61 63 6b 75 70 20 64 61 74 61 the backup data
3e900 62 61 73 65 20 69 73 20 74 72 61 6e 73 70 61 72 base is transpar
3e910 65 6e 74 6c 79 20 0a 2a 2a 20 75 70 64 61 74 65 ently .** update
3e920 64 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 d at the same ti
3e930 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 73 71 6c me..**.** <b>sql
3e940 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 ite3_backup_fini
3e950 73 68 28 29 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 4f sh()</b>.**.** O
3e960 6e 63 65 20 73 71 6c 69 74 65 33 5f 62 61 63 6b nce sqlite3_back
3e970 75 70 5f 73 74 65 70 28 29 20 68 61 73 20 72 65 up_step() has re
3e980 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 turned [SQLITE_D
3e990 4f 4e 45 5d 2c 20 6f 72 20 77 68 65 6e 20 74 68 ONE], or when th
3e9a0 65 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f e .** applicatio
3e9b0 6e 20 77 69 73 68 65 73 20 74 6f 20 61 62 61 6e n wishes to aban
3e9c0 64 6f 6e 20 74 68 65 20 62 61 63 6b 75 70 20 6f don the backup o
3e9d0 70 65 72 61 74 69 6f 6e 2c 20 74 68 65 20 5b 73 peration, the [s
3e9e0 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 0a 2a qlite3_backup].*
3e9f0 2a 20 6f 62 6a 65 63 74 20 73 68 6f 75 6c 64 20 * object should
3ea00 62 65 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c be passed to sql
3ea10 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 ite3_backup_fini
3ea20 73 68 28 29 2e 20 54 68 69 73 20 72 65 6c 65 61 sh(). This relea
3ea30 73 65 73 20 61 6c 6c 0a 2a 2a 20 72 65 73 6f 75 ses all.** resou
3ea40 72 63 65 73 20 61 73 73 6f 63 69 61 74 65 64 20 rces associated
3ea50 77 69 74 68 20 74 68 65 20 62 61 63 6b 75 70 20 with the backup
3ea60 6f 70 65 72 61 74 69 6f 6e 2e 20 49 66 20 73 71 operation. If sq
3ea70 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 lite3_backup_ste
3ea80 70 28 29 0a 2a 2a 20 68 61 73 20 6e 6f 74 20 79 p().** has not y
3ea90 65 74 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c et returned [SQL
3eaa0 49 54 45 5f 44 4f 4e 45 5d 2c 20 74 68 65 6e 20 ITE_DONE], then
3eab0 61 6e 79 20 61 63 74 69 76 65 20 77 72 69 74 65 any active write
3eac0 2d 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 6e 20 -transaction on
3ead0 74 68 65 0a 2a 2a 20 64 65 73 74 69 6e 61 74 69 the.** destinati
3eae0 6f 6e 20 64 61 74 61 62 61 73 65 20 69 73 20 72 on database is r
3eaf0 6f 6c 6c 65 64 20 62 61 63 6b 2e 20 54 68 65 20 olled back. The
3eb00 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d [sqlite3_backup]
3eb10 20 6f 62 6a 65 63 74 20 69 73 20 69 6e 76 61 6c object is inval
3eb20 69 64 0a 2a 2a 20 61 6e 64 20 6d 61 79 20 6e 6f id.** and may no
3eb30 74 20 62 65 20 75 73 65 64 20 66 6f 6c 6c 6f 77 t be used follow
3eb40 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 ing a call to sq
3eb50 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e lite3_backup_fin
3eb60 69 73 68 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ish()..**.** The
3eb70 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
3eb80 62 79 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 by sqlite3_backu
3eb90 70 5f 66 69 6e 69 73 68 20 69 73 20 5b 53 51 4c p_finish is [SQL
3eba0 49 54 45 5f 4f 4b 5d 20 69 66 20 6e 6f 20 65 72 ITE_OK] if no er
3ebb0 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 72 65 64 2c ror.** occurred,
3ebc0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 72 20 77 regardless or w
3ebd0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 71 hether or not sq
3ebe0 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 lite3_backup_ste
3ebf0 70 28 29 20 77 61 73 20 63 61 6c 6c 65 64 0a 2a p() was called.*
3ec00 2a 20 61 20 73 75 66 66 69 63 69 65 6e 74 20 6e * a sufficient n
3ec10 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 umber of times t
3ec20 6f 20 63 6f 6d 70 6c 65 74 65 20 74 68 65 20 62 o complete the b
3ec30 61 63 6b 75 70 20 6f 70 65 72 61 74 69 6f 6e 2e ackup operation.
3ec40 20 4f 72 2c 20 69 66 0a 2a 2a 20 61 6e 20 6f 75 Or, if.** an ou
3ec50 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 t-of-memory cond
3ec60 69 74 69 6f 6e 20 6f 72 20 49 4f 20 65 72 72 6f ition or IO erro
3ec70 72 20 6f 63 63 75 72 65 64 20 64 75 72 69 6e 67 r occured during
3ec80 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 a call to.** sq
3ec90 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 lite3_backup_ste
3eca0 70 28 29 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 p() then [SQLITE
3ecb0 5f 4e 4f 4d 45 4d 5d 20 6f 72 20 61 6e 0a 2a 2a _NOMEM] or an.**
3ecc0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 [SQLITE_IOERR_A
3ecd0 43 43 45 53 53 20 7c 20 53 51 4c 49 54 45 5f 49 CCESS | SQLITE_I
3ece0 4f 45 52 52 5f 58 58 58 5d 20 65 72 72 6f 72 20 OERR_XXX] error
3ecf0 63 6f 64 65 0a 2a 2a 20 69 73 20 72 65 74 75 72 code.** is retur
3ed00 6e 65 64 2e 20 49 6e 20 74 68 69 73 20 63 61 73 ned. In this cas
3ed10 65 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 e the error code
3ed20 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 and an error me
3ed30 73 73 61 67 65 20 61 72 65 0a 2a 2a 20 77 72 69 ssage are.** wri
3ed40 74 74 65 6e 20 74 6f 20 74 68 65 20 64 65 73 74 tten to the dest
3ed50 69 6e 61 74 69 6f 6e 20 5b 64 61 74 61 62 61 73 ination [databas
3ed60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a e connection]..*
3ed70 2a 0a 2a 2a 20 41 20 72 65 74 75 72 6e 20 6f 66 *.** A return of
3ed80 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f [SQLITE_BUSY] o
3ed90 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 r [SQLITE_LOCKED
3eda0 5d 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 62 ] from sqlite3_b
3edb0 61 63 6b 75 70 5f 73 74 65 70 28 29 20 69 73 0a ackup_step() is.
3edc0 2a 2a 20 6e 6f 74 20 61 20 70 65 72 6d 61 6e 65 ** not a permane
3edd0 6e 74 20 65 72 72 6f 72 20 61 6e 64 20 64 6f 65 nt error and doe
3ede0 73 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65 s not affect the
3edf0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 return value of
3ee00 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 6b .** sqlite3_back
3ee10 75 70 5f 66 69 6e 69 73 68 28 29 2e 0a 2a 2a 0a up_finish()..**.
3ee20 2a 2a 20 3c 62 3e 73 71 6c 69 74 65 33 5f 62 61 ** <b>sqlite3_ba
3ee30 63 6b 75 70 5f 72 65 6d 61 69 6e 69 6e 67 28 29 ckup_remaining()
3ee40 2c 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 , sqlite3_backup
3ee50 5f 70 61 67 65 63 6f 75 6e 74 28 29 3c 2f 62 3e _pagecount()</b>
3ee60 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 63 61 6c 6c .**.** Each call
3ee70 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b to sqlite3_back
3ee80 75 70 5f 73 74 65 70 28 29 20 73 65 74 73 20 74 up_step() sets t
3ee90 77 6f 20 76 61 6c 75 65 73 20 73 74 6f 72 65 64 wo values stored
3eea0 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 62 internally.** b
3eeb0 79 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 62 61 y an [sqlite3_ba
3eec0 63 6b 75 70 5d 20 6f 62 6a 65 63 74 2e 20 54 68 ckup] object. Th
3eed0 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 e number of page
3eee0 73 20 73 74 69 6c 6c 20 74 6f 20 62 65 20 62 61 s still to be ba
3eef0 63 6b 65 64 0a 2a 2a 20 75 70 2c 20 77 68 69 63 cked.** up, whic
3ef00 68 20 6d 61 79 20 62 65 20 71 75 65 72 69 65 64 h may be queried
3ef10 20 62 79 20 73 71 6c 69 74 65 33 5f 62 61 63 6b by sqlite3_back
3ef20 75 70 5f 72 65 6d 61 69 6e 69 6e 67 28 29 2c 20 up_remaining(),
3ef30 61 6e 64 20 74 68 65 20 74 6f 74 61 6c 0a 2a 2a and the total.**
3ef40 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 number of pages
3ef50 20 69 6e 20 74 68 65 20 73 6f 75 72 63 65 20 64 in the source d
3ef60 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 77 68 atabase file, wh
3ef70 69 63 68 20 6d 61 79 20 62 65 20 71 75 65 72 69 ich may be queri
3ef80 65 64 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 ed by.** sqlite3
3ef90 5f 62 61 63 6b 75 70 5f 70 61 67 65 63 6f 75 6e _backup_pagecoun
3efa0 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 t()..**.** The v
3efb0 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 alues returned b
3efc0 79 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e y these function
3efd0 73 20 61 72 65 20 6f 6e 6c 79 20 75 70 64 61 74 s are only updat
3efe0 65 64 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 ed by.** sqlite3
3eff0 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 2e 20 _backup_step().
3f000 49 66 20 74 68 65 20 73 6f 75 72 63 65 20 64 61 If the source da
3f010 74 61 62 61 73 65 20 69 73 20 6d 6f 64 69 66 69 tabase is modifi
3f020 65 64 20 64 75 72 69 6e 67 20 61 20 62 61 63 6b ed during a back
3f030 75 70 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 2c up.** operation,
3f040 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 73 then the values
3f050 20 61 72 65 20 6e 6f 74 20 75 70 64 61 74 65 64 are not updated
3f060 20 74 6f 20 61 63 63 6f 75 6e 74 20 66 6f 72 20 to account for
3f070 61 6e 79 20 65 78 74 72 61 0a 2a 2a 20 70 61 67 any extra.** pag
3f080 65 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 es that need to
3f090 62 65 20 75 70 64 61 74 65 64 20 6f 72 20 74 68 be updated or th
3f0a0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 6f e size of the so
3f0b0 75 72 63 65 20 64 61 74 61 62 61 73 65 20 66 69 urce database fi
3f0c0 6c 65 0a 2a 2a 20 63 68 61 6e 67 69 6e 67 2e 0a le.** changing..
3f0d0 2a 2a 0a 2a 2a 20 3c 62 3e 43 6f 6e 63 75 72 72 **.** <b>Concurr
3f0e0 65 6e 74 20 55 73 61 67 65 20 6f 66 20 44 61 74 ent Usage of Dat
3f0f0 61 62 61 73 65 20 48 61 6e 64 6c 65 73 3c 2f 62 abase Handles</b
3f100 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 6f 75 72 >.**.** The sour
3f110 63 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ce [database con
3f120 6e 65 63 74 69 6f 6e 5d 20 6d 61 79 20 62 65 20 nection] may be
3f130 75 73 65 64 20 62 79 20 74 68 65 20 61 70 70 6c used by the appl
3f140 69 63 61 74 69 6f 6e 20 66 6f 72 20 6f 74 68 65 ication for othe
3f150 72 0a 2a 2a 20 70 75 72 70 6f 73 65 73 20 77 68 r.** purposes wh
3f160 69 6c 65 20 61 20 62 61 63 6b 75 70 20 6f 70 65 ile a backup ope
3f170 72 61 74 69 6f 6e 20 69 73 20 75 6e 64 65 72 77 ration is underw
3f180 61 79 20 6f 72 20 62 65 69 6e 67 20 69 6e 69 74 ay or being init
3f190 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 49 66 20 53 ialized..** If S
3f1a0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
3f1b0 64 20 61 6e 64 20 63 6f 6e 66 69 67 75 72 65 64 d and configured
3f1c0 20 74 6f 20 73 75 70 70 6f 72 74 20 74 68 72 65 to support thre
3f1d0 61 64 73 61 66 65 20 64 61 74 61 62 61 73 65 0a adsafe database.
3f1e0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2c 20 ** connections,
3f1f0 74 68 65 6e 20 74 68 65 20 73 6f 75 72 63 65 20 then the source
3f200 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
3f210 69 6f 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20 ion may be used
3f220 63 6f 6e 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 concurrently.**
3f230 66 72 6f 6d 20 77 69 74 68 69 6e 20 6f 74 68 65 from within othe
3f240 72 20 74 68 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a r threads..**.**
3f250 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 61 70 However, the ap
3f260 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 67 plication must g
3f270 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 uarantee that th
3f280 65 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 e destination da
3f290 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 tabase.** connec
3f2a0 74 69 6f 6e 20 68 61 6e 64 6c 65 20 69 73 20 6e tion handle is n
3f2b0 6f 74 20 70 61 73 73 65 64 20 74 6f 20 61 6e 79 ot passed to any
3f2c0 20 6f 74 68 65 72 20 41 50 49 20 28 62 79 20 61 other API (by a
3f2d0 6e 79 20 74 68 72 65 61 64 29 20 61 66 74 65 72 ny thread) after
3f2e0 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 .** sqlite3_bac
3f2f0 6b 75 70 5f 69 6e 69 74 28 29 20 69 73 20 63 61 kup_init() is ca
3f300 6c 6c 65 64 20 61 6e 64 20 62 65 66 6f 72 65 20 lled and before
3f310 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e the correspondin
3f320 67 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c g call to.** sql
3f330 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 ite3_backup_fini
3f340 73 68 28 29 2e 20 55 6e 66 6f 72 74 75 6e 61 74 sh(). Unfortunat
3f350 65 6c 79 20 53 51 4c 69 74 65 20 64 6f 65 73 20 ely SQLite does
3f360 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 63 68 not currently ch
3f370 65 63 6b 0a 2a 2a 20 66 6f 72 20 74 68 69 73 2c eck.** for this,
3f380 20 69 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 if the applicat
3f390 69 6f 6e 20 64 6f 65 73 20 75 73 65 20 74 68 65 ion does use the
3f3a0 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 5b 64 61 destination [da
3f3b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
3f3c0 6e 5d 0a 2a 2a 20 66 6f 72 20 73 6f 6d 65 20 6f n].** for some o
3f3d0 74 68 65 72 20 70 75 72 70 6f 73 65 20 64 75 72 ther purpose dur
3f3e0 69 6e 67 20 61 20 62 61 63 6b 75 70 20 6f 70 65 ing a backup ope
3f3f0 72 61 74 69 6f 6e 2c 20 74 68 69 6e 67 73 20 6d ration, things m
3f400 61 79 20 61 70 70 65 61 72 20 74 6f 0a 2a 2a 20 ay appear to.**
3f410 77 6f 72 6b 20 63 6f 72 72 65 63 74 6c 79 20 62 work correctly b
3f420 75 74 20 69 6e 20 66 61 63 74 20 62 65 20 73 75 ut in fact be su
3f430 62 74 6c 79 20 6d 61 6c 66 75 6e 63 74 69 6f 6e btly malfunction
3f440 69 6e 67 2e 20 20 55 73 65 20 6f 66 20 74 68 65 ing. Use of the
3f450 0a 2a 2a 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 .** destination
3f460 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
3f470 69 6f 6e 20 77 68 69 6c 65 20 61 20 62 61 63 6b ion while a back
3f480 75 70 20 69 73 20 69 6e 20 70 72 6f 67 72 65 73 up is in progres
3f490 73 20 6d 69 67 68 74 0a 2a 2a 20 61 6c 73 6f 20 s might.** also
3f4a0 63 61 75 73 65 20 61 20 6d 75 74 65 78 20 64 65 cause a mutex de
3f4b0 61 64 6c 6f 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 75 adlock..**.** Fu
3f4c0 72 74 68 65 72 6d 6f 72 65 2c 20 69 66 20 72 75 rthermore, if ru
3f4d0 6e 6e 69 6e 67 20 69 6e 20 5b 73 68 61 72 65 64 nning in [shared
3f4e0 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 74 68 cache mode], th
3f4f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 e application mu
3f500 73 74 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 20 st.** guarantee
3f510 74 68 61 74 20 74 68 65 20 73 68 61 72 65 64 20 that the shared
3f520 63 61 63 68 65 20 75 73 65 64 20 62 79 20 74 68 cache used by th
3f530 65 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 e destination da
3f540 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 tabase.** is not
3f550 20 61 63 63 65 73 73 65 64 20 77 68 69 6c 65 20 accessed while
3f560 74 68 65 20 62 61 63 6b 75 70 20 69 73 20 72 75 the backup is ru
3f570 6e 6e 69 6e 67 2e 20 49 6e 20 70 72 61 63 74 69 nning. In practi
3f580 63 65 20 74 68 69 73 20 6d 65 61 6e 73 0a 2a 2a ce this means.**
3f590 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 that the applic
3f5a0 61 74 69 6f 6e 20 6d 75 73 74 20 67 75 61 72 61 ation must guara
3f5b0 6e 74 65 65 20 74 68 61 74 20 74 68 65 20 66 69 ntee that the fi
3f5c0 6c 65 2d 73 79 73 74 65 6d 20 66 69 6c 65 20 62 le-system file b
3f5d0 65 69 6e 67 20 0a 2a 2a 20 62 61 63 6b 65 64 20 eing .** backed
3f5e0 75 70 20 74 6f 20 69 73 20 6e 6f 74 20 61 63 63 up to is not acc
3f5f0 65 73 73 65 64 20 62 79 20 61 6e 79 20 63 6f 6e essed by any con
3f600 6e 65 63 74 69 6f 6e 20 77 69 74 68 69 6e 20 74 nection within t
3f610 68 65 20 70 72 6f 63 65 73 73 2c 0a 2a 2a 20 6e he process,.** n
3f620 6f 74 20 6a 75 73 74 20 74 68 65 20 73 70 65 63 ot just the spec
3f630 69 66 69 63 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 ific connection
3f640 74 68 61 74 20 77 61 73 20 70 61 73 73 65 64 20 that was passed
3f650 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 to sqlite3_backu
3f660 70 5f 69 6e 69 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 p_init()..**.**
3f670 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 The [sqlite3_bac
3f680 6b 75 70 5d 20 6f 62 6a 65 63 74 20 69 74 73 65 kup] object itse
3f690 6c 66 20 69 73 20 70 61 72 74 69 61 6c 6c 79 20 lf is partially
3f6a0 74 68 72 65 61 64 73 61 66 65 2e 20 4d 75 6c 74 threadsafe. Mult
3f6b0 69 70 6c 65 20 0a 2a 2a 20 74 68 72 65 61 64 73 iple .** threads
3f6c0 20 6d 61 79 20 73 61 66 65 6c 79 20 6d 61 6b 65 may safely make
3f6d0 20 6d 75 6c 74 69 70 6c 65 20 63 6f 6e 63 75 72 multiple concur
3f6e0 72 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 73 71 rent calls to sq
3f6f0 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 lite3_backup_ste
3f700 70 28 29 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c p()..** However,
3f710 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 61 63 the sqlite3_bac
3f720 6b 75 70 5f 72 65 6d 61 69 6e 69 6e 67 28 29 20 kup_remaining()
3f730 61 6e 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b and sqlite3_back
3f740 75 70 5f 70 61 67 65 63 6f 75 6e 74 28 29 0a 2a up_pagecount().*
3f750 2a 20 41 50 49 73 20 61 72 65 20 6e 6f 74 20 73 * APIs are not s
3f760 74 72 69 63 74 6c 79 20 73 70 65 61 6b 69 6e 67 trictly speaking
3f770 20 74 68 72 65 61 64 73 61 66 65 2e 20 49 66 20 threadsafe. If
3f780 74 68 65 79 20 61 72 65 20 69 6e 76 6f 6b 65 64 they are invoked
3f790 20 61 74 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 at the.** same
3f7a0 74 69 6d 65 20 61 73 20 61 6e 6f 74 68 65 72 20 time as another
3f7b0 74 68 72 65 61 64 20 69 73 20 69 6e 76 6f 6b 69 thread is invoki
3f7c0 6e 67 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 ng sqlite3_backu
3f7d0 70 5f 73 74 65 70 28 29 20 69 74 20 69 73 0a 2a p_step() it is.*
3f7e0 2a 20 70 6f 73 73 69 62 6c 65 20 74 68 61 74 20 * possible that
3f7f0 74 68 65 79 20 72 65 74 75 72 6e 20 69 6e 76 61 they return inva
3f800 6c 69 64 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 lid values..*/.S
3f810 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 QLITE_API sqlite
3f820 33 5f 62 61 63 6b 75 70 20 2a 73 71 6c 69 74 65 3_backup *sqlite
3f830 33 5f 62 61 63 6b 75 70 5f 69 6e 69 74 28 0a 20 3_backup_init(.
3f840 20 73 71 6c 69 74 65 33 20 2a 70 44 65 73 74 2c sqlite3 *pDest,
3f850 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3f860 20 20 20 20 20 20 20 20 2f 2a 20 44 65 73 74 69 /* Desti
3f870 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 73 65 20 nation database
3f880 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
3f890 74 20 63 68 61 72 20 2a 7a 44 65 73 74 4e 61 6d t char *zDestNam
3f8a0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 e,
3f8b0 20 20 20 2f 2a 20 44 65 73 74 69 6e 61 74 69 6f /* Destinatio
3f8c0 6e 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 n database name
3f8d0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 70 53 */. sqlite3 *pS
3f8e0 6f 75 72 63 65 2c 20 20 20 20 20 20 20 20 20 20 ource,
3f8f0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 /* S
3f900 6f 75 72 63 65 20 64 61 74 61 62 61 73 65 20 68 ource database h
3f910 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
3f920 20 63 68 61 72 20 2a 7a 53 6f 75 72 63 65 4e 61 char *zSourceNa
3f930 6d 65 20 20 20 20 20 20 20 20 20 20 20 20 20 20 me
3f940 20 20 2f 2a 20 53 6f 75 72 63 65 20 64 61 74 61 /* Source data
3f950 62 61 73 65 20 6e 61 6d 65 20 2a 2f 0a 29 3b 0a base name */.);.
3f960 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
3f970 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 qlite3_backup_st
3f980 65 70 28 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 ep(sqlite3_backu
3f990 70 20 2a 70 2c 20 69 6e 74 20 6e 50 61 67 65 29 p *p, int nPage)
3f9a0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
3f9b0 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f sqlite3_backup_
3f9c0 66 69 6e 69 73 68 28 73 71 6c 69 74 65 33 5f 62 finish(sqlite3_b
3f9d0 61 63 6b 75 70 20 2a 70 29 3b 0a 53 51 4c 49 54 ackup *p);.SQLIT
3f9e0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
3f9f0 33 5f 62 61 63 6b 75 70 5f 72 65 6d 61 69 6e 69 3_backup_remaini
3fa00 6e 67 28 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 ng(sqlite3_backu
3fa10 70 20 2a 70 29 3b 0a 53 51 4c 49 54 45 5f 41 50 p *p);.SQLITE_AP
3fa20 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 61 I int sqlite3_ba
3fa30 63 6b 75 70 5f 70 61 67 65 63 6f 75 6e 74 28 73 ckup_pagecount(s
3fa40 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 2a 70 qlite3_backup *p
3fa50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
3fa60 45 46 3a 20 55 6e 6c 6f 63 6b 20 4e 6f 74 69 66 EF: Unlock Notif
3fa70 69 63 61 74 69 6f 6e 0a 2a 2a 20 45 58 50 45 52 ication.** EXPER
3fa80 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 57 68 IMENTAL.**.** Wh
3fa90 65 6e 20 72 75 6e 6e 69 6e 67 20 69 6e 20 73 68 en running in sh
3faa0 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 2c ared-cache mode,
3fab0 20 61 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 a database oper
3fac0 61 74 69 6f 6e 20 6d 61 79 20 66 61 69 6c 20 77 ation may fail w
3fad0 69 74 68 0a 2a 2a 20 61 6e 20 5b 53 51 4c 49 54 ith.** an [SQLIT
3fae0 45 5f 4c 4f 43 4b 45 44 5d 20 65 72 72 6f 72 20 E_LOCKED] error
3faf0 69 66 20 74 68 65 20 72 65 71 75 69 72 65 64 20 if the required
3fb00 6c 6f 63 6b 73 20 6f 6e 20 74 68 65 20 73 68 61 locks on the sha
3fb10 72 65 64 2d 63 61 63 68 65 20 6f 72 0a 2a 2a 20 red-cache or.**
3fb20 69 6e 64 69 76 69 64 75 61 6c 20 74 61 62 6c 65 individual table
3fb30 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 68 61 s within the sha
3fb40 72 65 64 2d 63 61 63 68 65 20 63 61 6e 6e 6f 74 red-cache cannot
3fb50 20 62 65 20 6f 62 74 61 69 6e 65 64 2e 20 53 65 be obtained. Se
3fb60 65 0a 2a 2a 20 5b 53 51 4c 69 74 65 20 53 68 61 e.** [SQLite Sha
3fb70 72 65 64 2d 43 61 63 68 65 20 4d 6f 64 65 5d 20 red-Cache Mode]
3fb80 66 6f 72 20 61 20 64 65 73 63 72 69 70 74 69 6f for a descriptio
3fb90 6e 20 6f 66 20 73 68 61 72 65 64 2d 63 61 63 68 n of shared-cach
3fba0 65 20 6c 6f 63 6b 69 6e 67 2e 20 0a 2a 2a 20 54 e locking. .** T
3fbb0 68 69 73 20 41 50 49 20 6d 61 79 20 62 65 20 75 his API may be u
3fbc0 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 sed to register
3fbd0 61 20 63 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 a callback that
3fbe0 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f SQLite will invo
3fbf0 6b 65 20 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 ke .** when the
3fc00 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 75 72 72 65 connection curre
3fc10 6e 74 6c 79 20 68 6f 6c 64 69 6e 67 20 74 68 65 ntly holding the
3fc20 20 72 65 71 75 69 72 65 64 20 6c 6f 63 6b 20 72 required lock r
3fc30 65 6c 69 6e 71 75 69 73 68 65 73 20 69 74 2e 0a elinquishes it..
3fc40 2a 2a 20 54 68 69 73 20 41 50 49 20 69 73 20 6f ** This API is o
3fc50 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 nly available if
3fc60 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 the library was
3fc70 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 compiled with t
3fc80 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e he.** [SQLITE_EN
3fc90 41 42 4c 45 5f 55 4e 4c 4f 43 4b 5f 4e 4f 54 49 ABLE_UNLOCK_NOTI
3fca0 46 59 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 FY] C-preprocess
3fcb0 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 or symbol define
3fcc0 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 d..**.** See Als
3fcd0 6f 3a 20 5b 55 73 69 6e 67 20 74 68 65 20 53 51 o: [Using the SQ
3fce0 4c 69 74 65 20 55 6e 6c 6f 63 6b 20 4e 6f 74 69 Lite Unlock Noti
3fcf0 66 69 63 61 74 69 6f 6e 20 46 65 61 74 75 72 65 fication Feature
3fd00 5d 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65 64 2d ]..**.** Shared-
3fd10 63 61 63 68 65 20 6c 6f 63 6b 73 20 61 72 65 20 cache locks are
3fd20 72 65 6c 65 61 73 65 64 20 77 68 65 6e 20 61 20 released when a
3fd30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
3fd40 69 6f 6e 20 63 6f 6e 63 6c 75 64 65 73 0a 2a 2a ion concludes.**
3fd50 20 69 74 73 20 63 75 72 72 65 6e 74 20 74 72 61 its current tra
3fd60 6e 73 61 63 74 69 6f 6e 2c 20 65 69 74 68 65 72 nsaction, either
3fd70 20 62 79 20 63 6f 6d 6d 69 74 74 69 6e 67 20 69 by committing i
3fd80 74 20 6f 72 20 72 6f 6c 6c 69 6e 67 20 69 74 20 t or rolling it
3fd90 62 61 63 6b 2e 20 0a 2a 2a 0a 2a 2a 20 57 68 65 back. .**.** Whe
3fda0 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 28 n a connection (
3fdb0 6b 6e 6f 77 6e 20 61 73 20 74 68 65 20 62 6c 6f known as the blo
3fdc0 63 6b 65 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 29 cked connection)
3fdd0 20 66 61 69 6c 73 20 74 6f 20 6f 62 74 61 69 6e fails to obtain
3fde0 20 61 0a 2a 2a 20 73 68 61 72 65 64 2d 63 61 63 a.** shared-cac
3fdf0 68 65 20 6c 6f 63 6b 20 61 6e 64 20 53 51 4c 49 he lock and SQLI
3fe00 54 45 5f 4c 4f 43 4b 45 44 20 69 73 20 72 65 74 TE_LOCKED is ret
3fe10 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c urned to the cal
3fe20 6c 65 72 2c 20 74 68 65 0a 2a 2a 20 69 64 65 6e ler, the.** iden
3fe30 74 69 74 79 20 6f 66 20 74 68 65 20 64 61 74 61 tity of the data
3fe40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
3fe50 28 74 68 65 20 62 6c 6f 63 6b 69 6e 67 20 63 6f (the blocking co
3fe60 6e 6e 65 63 74 69 6f 6e 29 20 74 68 61 74 0a 2a nnection) that.*
3fe70 2a 20 68 61 73 20 6c 6f 63 6b 65 64 20 74 68 65 * has locked the
3fe80 20 72 65 71 75 69 72 65 64 20 72 65 73 6f 75 72 required resour
3fe90 63 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e 74 ce is stored int
3fea0 65 72 6e 61 6c 6c 79 2e 20 41 66 74 65 72 20 61 ernally. After a
3feb0 6e 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f n .** applicatio
3fec0 6e 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 n receives an SQ
3fed0 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 65 72 72 6f LITE_LOCKED erro
3fee0 72 2c 20 69 74 20 6d 61 79 20 63 61 6c 6c 20 74 r, it may call t
3fef0 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 6e he.** sqlite3_un
3ff00 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 20 6d 65 lock_notify() me
3ff10 74 68 6f 64 20 77 69 74 68 20 74 68 65 20 62 6c thod with the bl
3ff20 6f 63 6b 65 64 20 63 6f 6e 6e 65 63 74 69 6f 6e ocked connection
3ff30 20 68 61 6e 64 6c 65 20 61 73 20 0a 2a 2a 20 74 handle as .** t
3ff40 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
3ff50 74 20 74 6f 20 72 65 67 69 73 74 65 72 20 66 6f t to register fo
3ff60 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 74 68 61 r a callback tha
3ff70 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 t will be invoke
3ff80 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 62 6c d.** when the bl
3ff90 6f 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 69 6f ocking connectio
3ffa0 6e 73 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 ns current trans
3ffb0 61 63 74 69 6f 6e 20 69 73 20 63 6f 6e 63 6c 75 action is conclu
3ffc0 64 65 64 2e 20 54 68 65 0a 2a 2a 20 63 61 6c 6c ded. The.** call
3ffd0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
3ffe0 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 from within the
3fff0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 20 6f [sqlite3_step] o
40000 72 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 r [sqlite3_close
40010 5d 0a 2a 2a 20 63 61 6c 6c 20 74 68 61 74 20 63 ].** call that c
40020 6f 6e 63 6c 75 64 65 73 20 74 68 65 20 62 6c 6f oncludes the blo
40030 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 69 6f 6e cking connection
40040 73 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 0a 2a s transaction..*
40050 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f *.** If sqlite3_
40060 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 20 unlock_notify()
40070 69 73 20 63 61 6c 6c 65 64 20 69 6e 20 61 20 6d is called in a m
40080 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 ulti-threaded ap
40090 70 6c 69 63 61 74 69 6f 6e 2c 0a 2a 2a 20 74 68 plication,.** th
400a0 65 72 65 20 69 73 20 61 20 63 68 61 6e 63 65 20 ere is a chance
400b0 74 68 61 74 20 74 68 65 20 62 6c 6f 63 6b 69 6e that the blockin
400c0 67 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 69 6c g connection wil
400d0 6c 20 68 61 76 65 20 61 6c 72 65 61 64 79 0a 2a l have already.*
400e0 2a 20 63 6f 6e 63 6c 75 64 65 64 20 69 74 73 20 * concluded its
400f0 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 79 20 74 transaction by t
40100 68 65 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f he time sqlite3_
40110 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 20 unlock_notify()
40120 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 49 is invoked..** I
40130 66 20 74 68 69 73 20 68 61 70 70 65 6e 73 2c 20 f this happens,
40140 74 68 65 6e 20 74 68 65 20 73 70 65 63 69 66 69 then the specifi
40150 65 64 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 ed callback is i
40160 6e 76 6f 6b 65 64 20 69 6d 6d 65 64 69 61 74 65 nvoked immediate
40170 6c 79 2c 0a 2a 2a 20 66 72 6f 6d 20 77 69 74 68 ly,.** from with
40180 69 6e 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 in the call to s
40190 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f qlite3_unlock_no
401a0 74 69 66 79 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 tify()..**.** If
401b0 20 74 68 65 20 62 6c 6f 63 6b 65 64 20 63 6f 6e the blocked con
401c0 6e 65 63 74 69 6f 6e 20 69 73 20 61 74 74 65 6d nection is attem
401d0 70 74 69 6e 67 20 74 6f 20 6f 62 74 61 69 6e 20 pting to obtain
401e0 61 20 77 72 69 74 65 2d 6c 6f 63 6b 20 6f 6e 20 a write-lock on
401f0 61 0a 2a 2a 20 73 68 61 72 65 64 2d 63 61 63 68 a.** shared-cach
40200 65 20 74 61 62 6c 65 2c 20 61 6e 64 20 6d 6f 72 e table, and mor
40210 65 20 74 68 61 6e 20 6f 6e 65 20 6f 74 68 65 72 e than one other
40220 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 75 72 72 connection curr
40230 65 6e 74 6c 79 20 68 6f 6c 64 73 0a 2a 2a 20 61 ently holds.** a
40240 20 72 65 61 64 2d 6c 6f 63 6b 20 6f 6e 20 74 68 read-lock on th
40250 65 20 73 61 6d 65 20 74 61 62 6c 65 2c 20 74 68 e same table, th
40260 65 6e 20 53 51 4c 69 74 65 20 61 72 62 69 74 72 en SQLite arbitr
40270 61 72 69 6c 79 20 73 65 6c 65 63 74 73 20 6f 6e arily selects on
40280 65 20 6f 66 20 0a 2a 2a 20 74 68 65 20 6f 74 68 e of .** the oth
40290 65 72 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 74 er connections t
402a0 6f 20 75 73 65 20 61 73 20 74 68 65 20 62 6c 6f o use as the blo
402b0 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 69 6f 6e cking connection
402c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 6d 61 ..**.** There ma
402d0 79 20 62 65 20 61 74 20 6d 6f 73 74 20 6f 6e 65 y be at most one
402e0 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 unlock-notify c
402f0 61 6c 6c 62 61 63 6b 20 72 65 67 69 73 74 65 72 allback register
40300 65 64 20 62 79 20 61 20 0a 2a 2a 20 62 6c 6f 63 ed by a .** bloc
40310 6b 65 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 ked connection.
40320 49 66 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 If sqlite3_unloc
40330 6b 5f 6e 6f 74 69 66 79 28 29 20 69 73 20 63 61 k_notify() is ca
40340 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a lled when the.**
40350 20 62 6c 6f 63 6b 65 64 20 63 6f 6e 6e 65 63 74 blocked connect
40360 69 6f 6e 20 61 6c 72 65 61 64 79 20 68 61 73 20 ion already has
40370 61 20 72 65 67 69 73 74 65 72 65 64 20 75 6e 6c a registered unl
40380 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c 6c 62 ock-notify callb
40390 61 63 6b 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ack,.** then the
403a0 20 6e 65 77 20 63 61 6c 6c 62 61 63 6b 20 72 65 new callback re
403b0 70 6c 61 63 65 73 20 74 68 65 20 6f 6c 64 2e 20 places the old.
403c0 49 66 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 If sqlite3_unloc
403d0 6b 5f 6e 6f 74 69 66 79 28 29 20 69 73 0a 2a 2a k_notify() is.**
403e0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e called with a N
403f0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 73 20 69 ULL pointer as i
40400 74 73 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 ts second argume
40410 6e 74 2c 20 74 68 65 6e 20 61 6e 79 20 65 78 69 nt, then any exi
40420 73 74 69 6e 67 0a 2a 2a 20 75 6e 6c 6f 63 6b 2d sting.** unlock-
40430 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 notify callback
40440 69 73 20 63 61 6e 63 65 6c 6c 65 64 2e 20 54 68 is cancelled. Th
40450 65 20 62 6c 6f 63 6b 65 64 20 63 6f 6e 6e 65 63 e blocked connec
40460 74 69 6f 6e 73 20 0a 2a 2a 20 75 6e 6c 6f 63 6b tions .** unlock
40470 2d 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b -notify callback
40480 20 6d 61 79 20 61 6c 73 6f 20 62 65 20 63 61 6e may also be can
40490 63 65 6c 65 64 20 62 79 20 63 6c 6f 73 69 6e 67 celed by closing
404a0 20 74 68 65 20 62 6c 6f 63 6b 65 64 0a 2a 2a 20 the blocked.**
404b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 connection using
404c0 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 [sqlite3_close(
404d0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 6e )]..**.** The un
404e0 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c 6c lock-notify call
404f0 62 61 63 6b 20 69 73 20 6e 6f 74 20 72 65 65 6e back is not reen
40500 74 72 61 6e 74 2e 20 49 66 20 61 6e 20 61 70 70 trant. If an app
40510 6c 69 63 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 lication invokes
40520 0a 2a 2a 20 61 6e 79 20 73 71 6c 69 74 65 33 5f .** any sqlite3_
40530 78 78 78 20 41 50 49 20 66 75 6e 63 74 69 6f 6e xxx API function
40540 73 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 61 6e s from within an
40550 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 unlock-notify c
40560 61 6c 6c 62 61 63 6b 2c 20 61 0a 2a 2a 20 63 72 allback, a.** cr
40570 61 73 68 20 6f 72 20 64 65 61 64 6c 6f 63 6b 20 ash or deadlock
40580 6d 61 79 20 62 65 20 74 68 65 20 72 65 73 75 6c may be the resul
40590 74 2e 0a 2a 2a 0a 2a 2a 20 55 6e 6c 65 73 73 20 t..**.** Unless
405a0 64 65 61 64 6c 6f 63 6b 20 69 73 20 64 65 74 65 deadlock is dete
405b0 63 74 65 64 20 28 73 65 65 20 62 65 6c 6f 77 29 cted (see below)
405c0 2c 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b , sqlite3_unlock
405d0 5f 6e 6f 74 69 66 79 28 29 20 61 6c 77 61 79 73 _notify() always
405e0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 53 51 4c 49 .** returns SQLI
405f0 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e TE_OK..**.** <b>
40600 43 61 6c 6c 62 61 63 6b 20 49 6e 76 6f 63 61 74 Callback Invocat
40610 69 6f 6e 20 44 65 74 61 69 6c 73 3c 2f 62 3e 0a ion Details</b>.
40620 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 6e 20 75 6e **.** When an un
40630 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c 6c lock-notify call
40640 62 61 63 6b 20 69 73 20 72 65 67 69 73 74 65 72 back is register
40650 65 64 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 ed, the applicat
40660 69 6f 6e 20 70 72 6f 76 69 64 65 73 20 61 20 0a ion provides a .
40670 2a 2a 20 73 69 6e 67 6c 65 20 76 6f 69 64 2a 20 ** single void*
40680 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 pointer that is
40690 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 63 61 passed to the ca
406a0 6c 6c 62 61 63 6b 20 77 68 65 6e 20 69 74 20 69 llback when it i
406b0 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 48 6f s invoked..** Ho
406c0 77 65 76 65 72 2c 20 74 68 65 20 73 69 67 6e 61 wever, the signa
406d0 74 75 72 65 20 6f 66 20 74 68 65 20 63 61 6c 6c ture of the call
406e0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 61 6c back function al
406f0 6c 6f 77 73 20 53 51 4c 69 74 65 20 74 6f 20 70 lows SQLite to p
40700 61 73 73 0a 2a 2a 20 69 74 20 61 6e 20 61 72 72 ass.** it an arr
40710 61 79 20 6f 66 20 76 6f 69 64 2a 20 63 6f 6e 74 ay of void* cont
40720 65 78 74 20 70 6f 69 6e 74 65 72 73 2e 20 54 68 ext pointers. Th
40730 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
40740 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 61 6e passed to.** an
40750 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 unlock-notify c
40760 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 70 6f 69 allback is a poi
40770 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 nter to an array
40780 20 6f 66 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 of void* pointe
40790 72 73 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 rs,.** and the s
407a0 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d econd is the num
407b0 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20 69 ber of entries i
407c0 6e 20 74 68 65 20 61 72 72 61 79 2e 0a 2a 2a 0a n the array..**.
407d0 2a 2a 20 57 68 65 6e 20 61 20 62 6c 6f 63 6b 69 ** When a blocki
407e0 6e 67 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 74 ng connections t
407f0 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 6f ransaction is co
40800 6e 63 6c 75 64 65 64 2c 20 74 68 65 72 65 20 6d ncluded, there m
40810 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 74 68 ay be.** more th
40820 61 6e 20 6f 6e 65 20 62 6c 6f 63 6b 65 64 20 63 an one blocked c
40830 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 68 onnection that h
40840 61 73 20 72 65 67 69 73 74 65 72 65 64 20 66 6f as registered fo
40850 72 20 61 6e 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 r an unlock-noti
40860 66 79 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 2e 20 fy.** callback.
40870 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 73 If two or more s
40880 75 63 68 20 62 6c 6f 63 6b 65 64 20 63 6f 6e 6e uch blocked conn
40890 65 63 74 69 6f 6e 73 20 68 61 76 65 20 73 70 65 ections have spe
408a0 63 69 66 69 65 64 20 74 68 65 0a 2a 2a 20 73 61 cified the.** sa
408b0 6d 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 me callback func
408c0 74 69 6f 6e 2c 20 74 68 65 6e 20 69 6e 73 74 65 tion, then inste
408d0 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 ad of invoking t
408e0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 he callback func
408f0 74 69 6f 6e 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 tion.** multiple
40900 20 74 69 6d 65 73 2c 20 69 74 20 69 73 20 69 6e times, it is in
40910 76 6f 6b 65 64 20 6f 6e 63 65 20 77 69 74 68 20 voked once with
40920 74 68 65 20 73 65 74 20 6f 66 20 76 6f 69 64 2a the set of void*
40930 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 context pointer
40940 73 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 62 s.** specified b
40950 79 20 74 68 65 20 62 6c 6f 63 6b 65 64 20 63 6f y the blocked co
40960 6e 6e 65 63 74 69 6f 6e 73 20 62 75 6e 64 6c 65 nnections bundle
40970 64 20 74 6f 67 65 74 68 65 72 20 69 6e 74 6f 20 d together into
40980 61 6e 20 61 72 72 61 79 2e 0a 2a 2a 20 54 68 69 an array..** Thi
40990 73 20 67 69 76 65 73 20 74 68 65 20 61 70 70 6c s gives the appl
409a0 69 63 61 74 69 6f 6e 20 61 6e 20 6f 70 70 6f 72 ication an oppor
409b0 74 75 6e 69 74 79 20 74 6f 20 70 72 69 6f 72 69 tunity to priori
409c0 74 69 7a 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 tize any actions
409d0 20 0a 2a 2a 20 72 65 6c 61 74 65 64 20 74 6f 20 .** related to
409e0 74 68 65 20 73 65 74 20 6f 66 20 75 6e 62 6c 6f the set of unblo
409f0 63 6b 65 64 20 64 61 74 61 62 61 73 65 20 63 6f cked database co
40a00 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a nnections..**.**
40a10 20 3c 62 3e 44 65 61 64 6c 6f 63 6b 20 44 65 74 <b>Deadlock Det
40a20 65 63 74 69 6f 6e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a ection</b>.**.**
40a30 20 41 73 73 75 6d 69 6e 67 20 74 68 61 74 20 61 Assuming that a
40a40 66 74 65 72 20 72 65 67 69 73 74 65 72 69 6e 67 fter registering
40a50 20 66 6f 72 20 61 6e 20 75 6e 6c 6f 63 6b 2d 6e for an unlock-n
40a60 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 61 otify callback a
40a70 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 77 61 .** database wa
40a80 69 74 73 20 66 6f 72 20 74 68 65 20 63 61 6c 6c its for the call
40a90 62 61 63 6b 20 74 6f 20 62 65 20 69 73 73 75 65 back to be issue
40aa0 64 20 62 65 66 6f 72 65 20 74 61 6b 69 6e 67 20 d before taking
40ab0 61 6e 79 20 66 75 72 74 68 65 72 0a 2a 2a 20 61 any further.** a
40ac0 63 74 69 6f 6e 20 28 61 20 72 65 61 73 6f 6e 61 ction (a reasona
40ad0 62 6c 65 20 61 73 73 75 6d 70 74 69 6f 6e 29 2c ble assumption),
40ae0 20 74 68 65 6e 20 75 73 69 6e 67 20 74 68 69 73 then using this
40af0 20 41 50 49 20 6d 61 79 20 63 61 75 73 65 20 74 API may cause t
40b00 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f he.** applicatio
40b10 6e 20 74 6f 20 64 65 61 64 6c 6f 63 6b 2e 20 46 n to deadlock. F
40b20 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 63 or example, if c
40b30 6f 6e 6e 65 63 74 69 6f 6e 20 58 20 69 73 20 77 onnection X is w
40b40 61 69 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 63 6f aiting for.** co
40b50 6e 6e 65 63 74 69 6f 6e 20 59 27 73 20 74 72 61 nnection Y's tra
40b60 6e 73 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 nsaction to be c
40b70 6f 6e 63 6c 75 64 65 64 2c 20 61 6e 64 20 73 69 oncluded, and si
40b80 6d 69 6c 61 72 6c 79 20 63 6f 6e 6e 65 63 74 69 milarly connecti
40b90 6f 6e 0a 2a 2a 20 59 20 69 73 20 77 61 69 74 69 on.** Y is waiti
40ba0 6e 67 20 6f 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e ng on connection
40bb0 20 58 27 73 20 74 72 61 6e 73 61 63 74 69 6f 6e X's transaction
40bc0 2c 20 74 68 65 6e 20 6e 65 69 74 68 65 72 20 63 , then neither c
40bd0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c onnection.** wil
40be0 6c 20 70 72 6f 63 65 65 64 20 61 6e 64 20 74 68 l proceed and th
40bf0 65 20 73 79 73 74 65 6d 20 6d 61 79 20 72 65 6d e system may rem
40c00 61 69 6e 20 64 65 61 64 6c 6f 63 6b 65 64 20 69 ain deadlocked i
40c10 6e 64 65 66 69 6e 69 74 65 6c 79 2e 0a 2a 2a 0a ndefinitely..**.
40c20 2a 2a 20 54 6f 20 61 76 6f 69 64 20 74 68 69 73 ** To avoid this
40c30 20 73 63 65 6e 61 72 69 6f 2c 20 74 68 65 20 73 scenario, the s
40c40 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f qlite3_unlock_no
40c50 74 69 66 79 28 29 20 70 65 72 66 6f 72 6d 73 20 tify() performs
40c60 64 65 61 64 6c 6f 63 6b 0a 2a 2a 20 64 65 74 65 deadlock.** dete
40c70 63 74 69 6f 6e 2e 20 49 66 20 61 20 67 69 76 65 ction. If a give
40c80 6e 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 n call to sqlite
40c90 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 3_unlock_notify(
40ca0 29 20 77 6f 75 6c 64 20 70 75 74 20 74 68 65 0a ) would put the.
40cb0 2a 2a 20 73 79 73 74 65 6d 20 69 6e 20 61 20 64 ** system in a d
40cc0 65 61 64 6c 6f 63 6b 65 64 20 73 74 61 74 65 2c eadlocked state,
40cd0 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4c 4f 43 then SQLITE_LOC
40ce0 4b 45 44 20 69 73 20 72 65 74 75 72 6e 65 64 20 KED is returned
40cf0 61 6e 64 20 6e 6f 0a 2a 2a 20 75 6e 6c 6f 63 6b and no.** unlock
40d00 2d 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b -notify callback
40d10 20 69 73 20 72 65 67 69 73 74 65 72 65 64 2e 20 is registered.
40d20 54 68 65 20 73 79 73 74 65 6d 20 69 73 20 73 61 The system is sa
40d30 69 64 20 74 6f 20 62 65 20 69 6e 0a 2a 2a 20 61 id to be in.** a
40d40 20 64 65 61 64 6c 6f 63 6b 65 64 20 73 74 61 74 deadlocked stat
40d50 65 20 69 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 e if connection
40d60 41 20 68 61 73 20 72 65 67 69 73 74 65 72 65 64 A has registered
40d70 20 66 6f 72 20 61 6e 20 75 6e 6c 6f 63 6b 2d 6e for an unlock-n
40d80 6f 74 69 66 79 0a 2a 2a 20 63 61 6c 6c 62 61 63 otify.** callbac
40d90 6b 20 6f 6e 20 74 68 65 20 63 6f 6e 63 6c 75 73 k on the conclus
40da0 69 6f 6e 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f ion of connectio
40db0 6e 20 42 27 73 20 74 72 61 6e 73 61 63 74 69 6f n B's transactio
40dc0 6e 2c 20 61 6e 64 20 63 6f 6e 6e 65 63 74 69 6f n, and connectio
40dd0 6e 0a 2a 2a 20 42 20 68 61 73 20 69 74 73 65 6c n.** B has itsel
40de0 66 20 72 65 67 69 73 74 65 72 65 64 20 66 6f 72 f registered for
40df0 20 61 6e 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 an unlock-notif
40e00 79 20 63 61 6c 6c 62 61 63 6b 20 77 68 65 6e 20 y callback when
40e10 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 41 27 connection.** A'
40e20 73 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 s transaction is
40e30 20 63 6f 6e 63 6c 75 64 65 64 2e 20 49 6e 64 69 concluded. Indi
40e40 72 65 63 74 20 64 65 61 64 6c 6f 63 6b 20 69 73 rect deadlock is
40e50 20 61 6c 73 6f 20 64 65 74 65 63 74 65 64 2c 20 also detected,
40e60 73 6f 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d so.** the system
40e70 20 69 73 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 is also conside
40e80 72 65 64 20 74 6f 20 62 65 20 64 65 61 64 6c 6f red to be deadlo
40e90 63 6b 65 64 20 69 66 20 63 6f 6e 6e 65 63 74 69 cked if connecti
40ea0 6f 6e 20 42 20 68 61 73 0a 2a 2a 20 72 65 67 69 on B has.** regi
40eb0 73 74 65 72 65 64 20 66 6f 72 20 61 6e 20 75 6e stered for an un
40ec0 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c 6c lock-notify call
40ed0 62 61 63 6b 20 6f 6e 20 74 68 65 20 63 6f 6e 63 back on the conc
40ee0 6c 75 73 69 6f 6e 20 6f 66 20 63 6f 6e 6e 65 63 lusion of connec
40ef0 74 69 6f 6e 0a 2a 2a 20 43 27 73 20 74 72 61 6e tion.** C's tran
40f00 73 61 63 74 69 6f 6e 2c 20 77 68 65 72 65 20 63 saction, where c
40f10 6f 6e 6e 65 63 74 69 6f 6e 20 43 20 69 73 20 77 onnection C is w
40f20 61 69 74 69 6e 67 20 6f 6e 20 63 6f 6e 6e 65 63 aiting on connec
40f30 74 69 6f 6e 20 41 2e 20 41 6e 79 0a 2a 2a 20 6e tion A. Any.** n
40f40 75 6d 62 65 72 20 6f 66 20 6c 65 76 65 6c 73 20 umber of levels
40f50 6f 66 20 69 6e 64 69 72 65 63 74 69 6f 6e 20 61 of indirection a
40f60 72 65 20 61 6c 6c 6f 77 65 64 2e 0a 2a 2a 0a 2a re allowed..**.*
40f70 2a 20 3c 62 3e 54 68 65 20 22 44 52 4f 50 20 54 * <b>The "DROP T
40f80 41 42 4c 45 22 20 45 78 63 65 70 74 69 6f 6e 3c ABLE" Exception<
40f90 2f 62 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 /b>.**.** When a
40fa0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
40fb0 33 5f 73 74 65 70 28 29 5d 20 72 65 74 75 72 6e 3_step()] return
40fc0 73 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 2c s SQLITE_LOCKED,
40fd0 20 69 74 20 69 73 20 61 6c 6d 6f 73 74 20 0a 2a it is almost .*
40fe0 2a 20 61 6c 77 61 79 73 20 61 70 70 72 6f 70 72 * always appropr
40ff0 69 61 74 65 20 74 6f 20 63 61 6c 6c 20 73 71 6c iate to call sql
41000 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 ite3_unlock_noti
41010 66 79 28 29 2e 20 54 68 65 72 65 20 69 73 20 68 fy(). There is h
41020 6f 77 65 76 65 72 2c 0a 2a 2a 20 6f 6e 65 20 65 owever,.** one e
41030 78 63 65 70 74 69 6f 6e 2e 20 57 68 65 6e 20 65 xception. When e
41040 78 65 63 75 74 69 6e 67 20 61 20 22 44 52 4f 50 xecuting a "DROP
41050 20 54 41 42 4c 45 22 20 6f 72 20 22 44 52 4f 50 TABLE" or "DROP
41060 20 49 4e 44 45 58 22 20 73 74 61 74 65 6d 65 6e INDEX" statemen
41070 74 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 63 68 65 t,.** SQLite che
41080 63 6b 73 20 69 66 20 74 68 65 72 65 20 61 72 65 cks if there are
41090 20 61 6e 79 20 63 75 72 72 65 6e 74 6c 79 20 65 any currently e
410a0 78 65 63 75 74 69 6e 67 20 53 45 4c 45 43 54 20 xecuting SELECT
410b0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 statements.** th
410c0 61 74 20 62 65 6c 6f 6e 67 20 74 6f 20 74 68 65 at belong to the
410d0 20 73 61 6d 65 20 63 6f 6e 6e 65 63 74 69 6f 6e same connection
410e0 2e 20 49 66 20 74 68 65 72 65 20 61 72 65 2c 20 . If there are,
410f0 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 69 73 SQLITE_LOCKED is
41100 0a 2a 2a 20 72 65 74 75 72 6e 65 64 2e 20 49 6e .** returned. In
41110 20 74 68 69 73 20 63 61 73 65 20 74 68 65 72 65 this case there
41120 20 69 73 20 6e 6f 20 22 62 6c 6f 63 6b 69 6e 67 is no "blocking
41130 20 63 6f 6e 6e 65 63 74 69 6f 6e 22 2c 20 73 6f connection", so
41140 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c invoking.** sql
41150 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 ite3_unlock_noti
41160 66 79 28 29 20 72 65 73 75 6c 74 73 20 69 6e 20 fy() results in
41170 74 68 65 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 the unlock-notif
41180 79 20 63 61 6c 6c 62 61 63 6b 20 62 65 69 6e 67 y callback being
41190 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 69 6d 6d 65 .** invoked imme
411a0 64 69 61 74 65 6c 79 2e 20 49 66 20 74 68 65 20 diately. If the
411b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 65 6e application then
411c0 20 72 65 2d 61 74 74 65 6d 70 74 73 20 74 68 65 re-attempts the
411d0 20 22 44 52 4f 50 20 54 41 42 4c 45 22 0a 2a 2a "DROP TABLE".**
411e0 20 6f 72 20 22 44 52 4f 50 20 49 4e 44 45 58 22 or "DROP INDEX"
411f0 20 71 75 65 72 79 2c 20 61 6e 20 69 6e 66 69 6e query, an infin
41200 69 74 65 20 6c 6f 6f 70 20 6d 69 67 68 74 20 62 ite loop might b
41210 65 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a e the result..**
41220 0a 2a 2a 20 4f 6e 65 20 77 61 79 20 61 72 6f 75 .** One way arou
41230 6e 64 20 74 68 69 73 20 70 72 6f 62 6c 65 6d 20 nd this problem
41240 69 73 20 74 6f 20 63 68 65 63 6b 20 74 68 65 20 is to check the
41250 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 extended error c
41260 6f 64 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 ode returned.**
41270 62 79 20 61 6e 20 73 71 6c 69 74 65 33 5f 73 74 by an sqlite3_st
41280 65 70 28 29 20 63 61 6c 6c 2e 20 49 66 20 74 68 ep() call. If th
41290 65 72 65 20 69 73 20 61 20 62 6c 6f 63 6b 69 6e ere is a blockin
412a0 67 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 g connection, th
412b0 65 6e 20 74 68 65 0a 2a 2a 20 65 78 74 65 6e 64 en the.** extend
412c0 65 64 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 ed error code is
412d0 20 73 65 74 20 74 6f 20 53 51 4c 49 54 45 5f 4c set to SQLITE_L
412e0 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 OCKED_SHAREDCACH
412f0 45 2e 20 4f 74 68 65 72 77 69 73 65 2c 20 69 6e E. Otherwise, in
41300 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 .** the special
41310 22 44 52 4f 50 20 54 41 42 4c 45 2f 49 4e 44 45 "DROP TABLE/INDE
41320 58 22 20 63 61 73 65 2c 20 74 68 65 20 65 78 74 X" case, the ext
41330 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 ended error code
41340 20 69 73 20 6a 75 73 74 20 0a 2a 2a 20 53 51 4c is just .** SQL
41350 49 54 45 5f 4c 4f 43 4b 45 44 2e 0a 2a 2f 0a 53 ITE_LOCKED..*/.S
41360 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
41370 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 lite3_unlock_not
41380 69 66 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a ify(. sqlite3 *
41390 70 42 6c 6f 63 6b 65 64 2c 20 20 20 20 20 20 20 pBlocked,
413a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
413b0 20 20 20 2f 2a 20 57 61 69 74 69 6e 67 20 63 6f /* Waiting co
413c0 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f nnection */. vo
413d0 69 64 20 28 2a 78 4e 6f 74 69 66 79 29 28 76 6f id (*xNotify)(vo
413e0 69 64 20 2a 2a 61 70 41 72 67 2c 20 69 6e 74 20 id **apArg, int
413f0 6e 41 72 67 29 2c 20 20 20 20 2f 2a 20 43 61 6c nArg), /* Cal
41400 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 lback function t
41410 6f 20 69 6e 76 6f 6b 65 20 2a 2f 0a 20 20 76 6f o invoke */. vo
41420 69 64 20 2a 70 4e 6f 74 69 66 79 41 72 67 20 20 id *pNotifyArg
41430 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
41440 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 /* Arg
41450 75 6d 65 6e 74 20 74 6f 20 70 61 73 73 20 74 6f ument to pass to
41460 20 78 4e 6f 74 69 66 79 20 2a 2f 0a 29 3b 0a 0a xNotify */.);..
41470 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
41480 20 53 74 72 69 6e 67 20 43 6f 6d 70 61 72 69 73 String Comparis
41490 6f 6e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 on.** EXPERIMENT
414a0 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 AL.**.** The [sq
414b0 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 lite3_strnicmp()
414c0 5d 20 41 50 49 20 61 6c 6c 6f 77 73 20 61 70 70 ] API allows app
414d0 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 65 78 lications and ex
414e0 74 65 6e 73 69 6f 6e 73 20 74 6f 0a 2a 2a 20 63 tensions to.** c
414f0 6f 6d 70 61 72 65 20 74 68 65 20 63 6f 6e 74 65 ompare the conte
41500 6e 74 73 20 6f 66 20 74 77 6f 20 62 75 66 66 65 nts of two buffe
41510 72 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 55 54 rs containing UT
41520 46 2d 38 20 73 74 72 69 6e 67 73 20 69 6e 20 61 F-8 strings in a
41530 0a 2a 2a 20 63 61 73 65 2d 69 6e 64 65 6e 64 65 .** case-indende
41540 6e 74 20 66 61 73 68 69 6f 6e 2c 20 75 73 69 6e nt fashion, usin
41550 67 20 74 68 65 20 73 61 6d 65 20 64 65 66 69 6e g the same defin
41560 69 74 69 6f 6e 20 6f 66 20 63 61 73 65 20 69 6e ition of case in
41570 64 65 70 65 6e 64 65 6e 63 65 20 0a 2a 2a 20 74 dependence .** t
41580 68 61 74 20 53 51 4c 69 74 65 20 75 73 65 73 20 hat SQLite uses
41590 69 6e 74 65 72 6e 61 6c 6c 79 20 77 68 65 6e 20 internally when
415a0 63 6f 6d 70 61 72 69 6e 67 20 69 64 65 6e 74 69 comparing identi
415b0 66 69 65 72 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 fiers..*/.SQLITE
415c0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
415d0 5f 73 74 72 6e 69 63 6d 70 28 63 6f 6e 73 74 20 _strnicmp(const
415e0 63 68 61 72 20 2a 2c 20 63 6f 6e 73 74 20 63 68 char *, const ch
415f0 61 72 20 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a ar *, int);../*.
41600 2a 2a 20 55 6e 64 6f 20 74 68 65 20 68 61 63 6b ** Undo the hack
41610 20 74 68 61 74 20 63 6f 6e 76 65 72 74 73 20 66 that converts f
41620 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 74 79 loating point ty
41630 70 65 73 20 74 6f 20 69 6e 74 65 67 65 72 20 66 pes to integer f
41640 6f 72 0a 2a 2a 20 62 75 69 6c 64 73 20 6f 6e 20 or.** builds on
41650 70 72 6f 63 65 73 73 6f 72 73 20 77 69 74 68 6f processors witho
41660 75 74 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e ut floating poin
41670 74 20 73 75 70 70 6f 72 74 2e 0a 2a 2f 0a 23 69 t support..*/.#i
41680 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 fdef SQLITE_OMIT
41690 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a _FLOATING_POINT.
416a0 23 20 75 6e 64 65 66 20 64 6f 75 62 6c 65 0a 23 # undef double.#
416b0 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 5f 5f endif..#ifdef __
416c0 63 70 6c 75 73 70 6c 75 73 0a 7d 20 20 2f 2a 20 cplusplus.} /*
416d0 45 6e 64 20 6f 66 20 74 68 65 20 27 65 78 74 65 End of the 'exte
416e0 72 6e 20 22 43 22 27 20 62 6c 6f 63 6b 20 2a 2f rn "C"' block */
416f0 0a 23 65 6e 64 69 66 0a 23 65 6e 64 69 66 0a 0a .#endif.#endif..