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 32 31 22 0a 23 64 65 66 69 "3.6.21".#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 32 31 N_NUMBER 3006021
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 31 32 2d 30 37 20 31 36 3a 33 39 2009-12-07 16:39
1170: 3a 31 33 20 31 65 64 38 38 65 39 64 30 31 65 39 :13 1ed88e9d01e9
1180: 65 64 61 35 63 62 63 36 32 32 65 37 36 31 34 32 eda5cbc622e76142
1190: 37 37 66 32 39 62 63 63 35 35 31 63 22 0a 0a 2f 77f29bcc551c"../
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 6d 75 73 74 20 5b 73 71 6c 69 74 65 33 ns must [sqlite3
24e0: 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 _finalize | fina
24f0: 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 lize] all [prepa
2500: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 0a red statements].
2510: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ** and [sqlite3_
2520: 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f blob_close | clo
2530: 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 se] all [BLOB ha
2540: 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74 65 ndles] associate
2550: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 73 d with.** the [s
2560: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 qlite3] object p
2570: 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 rior to attempti
2580: 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 ng to close the
2590: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 object..**.** If
25a0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 [sqlite3_close(
25b0: 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 )] is invoked wh
25c0: 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69 6f ile a transactio
25d0: 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 n is open,.** th
25e0: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 e transaction is
25f0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 automatically r
2600: 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a olled back..**.*
2610: 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65 74 65 * The C paramete
2620: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c r to [sqlite3_cl
2630: 6f 73 65 28 43 29 5d 20 6d 75 73 74 20 62 65 20 ose(C)] must be
2640: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a either a NULL.**
2650: 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b pointer or an [
2660: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 sqlite3] object
2670: 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 pointer obtained
2680: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 .** from [sqlite
2690: 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 3_open()], [sqli
26a0: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f te3_open16()], o
26b0: 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 r.** [sqlite3_op
26c0: 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f en_v2()], and no
26d0: 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f t previously clo
26e0: 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 sed..**.** Requi
26f0: 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 rements:.** [H12
2700: 30 31 31 5d 20 5b 48 31 32 30 31 32 5d 20 5b 48 011] [H12012] [H
2710: 31 32 30 31 33 5d 20 5b 48 31 32 30 31 34 5d 20 12013] [H12014]
2720: 5b 48 31 32 30 31 35 5d 20 5b 48 31 32 30 31 39 [H12015] [H12019
2730: 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
2740: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 int sqlite3_clos
2750: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f e(sqlite3 *);../
2760: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f *.** The type fo
2770: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e r a callback fun
2780: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 ction..** This i
2790: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 s legacy and dep
27a0: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 recated. It is
27b0: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 included for his
27c0: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 torical.** compa
27d0: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 tibility and is
27e0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a not documented..
27f0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 */.typedef int (
2800: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 *sqlite3_callbac
2810: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 k)(void*,int,cha
2820: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f r**, char**);../
2830: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
2840: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 ne-Step Query Ex
2850: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 ecution Interfac
2860: 65 20 7b 48 31 32 31 30 30 7d 20 3c 53 31 30 30 e {H12100} <S100
2870: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 00>.**.** The sq
2880: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 lite3_exec() int
2890: 65 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 erface is a conv
28a0: 65 6e 69 65 6e 74 20 77 61 79 20 6f 66 20 72 75 enient way of ru
28b0: 6e 6e 69 6e 67 20 6f 6e 65 20 6f 72 20 6d 6f 72 nning one or mor
28c0: 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 e.** SQL stateme
28d0: 6e 74 73 20 77 69 74 68 6f 75 74 20 68 61 76 69 nts without havi
28e0: 6e 67 20 74 6f 20 77 72 69 74 65 20 61 20 6c 6f ng to write a lo
28f0: 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 20 54 68 t of C code. Th
2900: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 0a e UTF-8 encoded.
2910: 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ** SQL statement
2920: 73 20 61 72 65 20 70 61 73 73 65 64 20 69 6e 20 s are passed in
2930: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 as the second pa
2940: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
2950: 65 33 5f 65 78 65 63 28 29 2e 0a 2a 2a 20 54 68 e3_exec()..** Th
2960: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 e statements are
2970: 20 65 76 61 6c 75 61 74 65 64 20 6f 6e 65 20 62 evaluated one b
2980: 79 20 6f 6e 65 20 75 6e 74 69 6c 20 65 69 74 68 y one until eith
2990: 65 72 20 61 6e 20 65 72 72 6f 72 20 6f 72 0a 2a er an error or.*
29a0: 2a 20 61 6e 20 69 6e 74 65 72 72 75 70 74 20 69 * an interrupt i
29b0: 73 20 65 6e 63 6f 75 6e 74 65 72 65 64 2c 20 6f s encountered, o
29c0: 72 20 75 6e 74 69 6c 20 74 68 65 79 20 61 72 65 r until they are
29d0: 20 61 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 65 20 all done. The
29e0: 33 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 3rd parameter.**
29f0: 20 69 73 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 is an optional
2a00: 63 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 69 73 callback that is
2a10: 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f invoked once fo
2a20: 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20 61 6e r each row of an
2a30: 79 20 71 75 65 72 79 0a 2a 2a 20 72 65 73 75 6c y query.** resul
2a40: 74 73 20 70 72 6f 64 75 63 65 64 20 62 79 20 74 ts produced by t
2a50: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
2a60: 73 2e 20 20 54 68 65 20 35 74 68 20 70 61 72 61 s. The 5th para
2a70: 6d 65 74 65 72 20 74 65 6c 6c 73 20 77 68 65 72 meter tells wher
2a80: 65 0a 2a 2a 20 74 6f 20 77 72 69 74 65 20 61 6e e.** to write an
2a90: 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 73 y error messages
2aa0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 72 72 6f ..**.** The erro
2ab0: 72 20 6d 65 73 73 61 67 65 20 70 61 73 73 65 64 r message passed
2ac0: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 back through th
2ad0: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 5th parameter
2ae0: 69 73 20 68 65 6c 64 0a 2a 2a 20 69 6e 20 6d 65 is held.** in me
2af0: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 mory obtained fr
2b00: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
2b10: 6f 63 28 29 5d 2e 20 20 54 6f 20 61 76 6f 69 64 oc()]. To avoid
2b20: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2c 0a a memory leak,.
2b30: 2a 2a 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 61 ** the calling a
2b40: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
2b50: 64 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f d call [sqlite3_
2b60: 66 72 65 65 28 29 5d 20 6f 6e 20 61 6e 79 20 65 free()] on any e
2b70: 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 rror.** message
2b80: 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 returned through
2b90: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 the 5th paramet
2ba0: 65 72 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 er when it has f
2bb0: 69 6e 69 73 68 65 64 20 75 73 69 6e 67 0a 2a 2a inished using.**
2bc0: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 the error messa
2bd0: 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 ge..**.** If the
2be0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 SQL statement i
2bf0: 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 n the 2nd parame
2c00: 74 65 72 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 ter is NULL or a
2c10: 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 0a 2a n empty string.*
2c20: 2a 20 6f 72 20 61 20 73 74 72 69 6e 67 20 63 6f * or a string co
2c30: 6e 74 61 69 6e 69 6e 67 20 6f 6e 6c 79 20 77 68 ntaining only wh
2c40: 69 74 65 73 70 61 63 65 20 61 6e 64 20 63 6f 6d itespace and com
2c50: 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 ments, then no S
2c60: 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 QL.** statements
2c70: 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 are evaluated a
2c80: 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 nd the database
2c90: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a is not changed..
2ca0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
2cb0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 3_exec() interfa
2cc0: 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 ce is implemente
2cd0: 64 20 69 6e 20 74 65 72 6d 73 20 6f 66 0a 2a 2a d in terms of.**
2ce0: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2cf0: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 e_v2()], [sqlite
2d00: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 3_step()], and [
2d10: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
2d20: 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ()]..** The sqli
2d30: 74 65 33 5f 65 78 65 63 28 29 20 72 6f 75 74 69 te3_exec() routi
2d40: 6e 65 20 64 6f 65 73 20 6e 6f 74 68 69 6e 67 20 ne does nothing
2d50: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 to the database
2d60: 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 64 that cannot be d
2d70: 6f 6e 65 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 one.** by [sqlit
2d80: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
2d90: 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 , [sqlite3_step(
2da0: 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 )], and [sqlite3
2db0: 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a _finalize()]..**
2dc0: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 .** The first pa
2dd0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
2de0: 74 65 33 5f 65 78 65 63 28 29 5d 20 6d 75 73 74 te3_exec()] must
2df0: 20 62 65 20 61 6e 20 76 61 6c 69 64 20 61 6e 64 be an valid and
2e00: 20 6f 70 65 6e 0a 2a 2a 20 5b 64 61 74 61 62 61 open.** [databa
2e10: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a se connection]..
2e20: 2a 2a 0a 2a 2a 20 54 68 65 20 64 61 74 61 62 61 **.** The databa
2e30: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 se connection mu
2e40: 73 74 20 6e 6f 74 20 62 65 20 63 6c 6f 73 65 64 st not be closed
2e50: 20 77 68 69 6c 65 0a 2a 2a 20 5b 73 71 6c 69 74 while.** [sqlit
2e60: 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 e3_exec()] is ru
2e70: 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 nning..**.** The
2e80: 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f calling functio
2e90: 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 5b 73 71 n should use [sq
2ea0: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 74 6f lite3_free()] to
2eb0: 20 66 72 65 65 0a 2a 2a 20 74 68 65 20 6d 65 6d free.** the mem
2ec0: 6f 72 79 20 74 68 61 74 20 2a 65 72 72 6d 73 67 ory that *errmsg
2ed0: 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e is left pointin
2ee0: 67 20 61 74 20 6f 6e 63 65 20 74 68 65 20 65 72 g at once the er
2ef0: 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 69 ror.** message i
2f00: 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 s no longer need
2f10: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 ed..**.** The SQ
2f20: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 L statement text
2f30: 20 69 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61 in the 2nd para
2f40: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 meter to [sqlite
2f50: 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 6d 75 73 3_exec()].** mus
2f60: 74 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 t remain unchang
2f70: 65 64 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 ed while [sqlite
2f80: 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e 3_exec()] is run
2f90: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 ning..**.** Requ
2fa0: 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
2fb0: 32 31 30 31 5d 20 5b 48 31 32 31 30 32 5d 20 5b 2101] [H12102] [
2fc0: 48 31 32 31 30 34 5d 20 5b 48 31 32 31 30 35 5d H12104] [H12105]
2fd0: 20 5b 48 31 32 31 30 37 5d 20 5b 48 31 32 31 31 [H12107] [H1211
2fe0: 30 5d 20 5b 48 31 32 31 31 33 5d 20 5b 48 31 32 0] [H12113] [H12
2ff0: 31 31 36 5d 0a 2a 2a 20 5b 48 31 32 31 31 39 5d 116].** [H12119]
3000: 20 5b 48 31 32 31 32 32 5d 20 5b 48 31 32 31 32 [H12122] [H1212
3010: 35 5d 20 5b 48 31 32 31 33 31 5d 20 5b 48 31 32 5] [H12131] [H12
3020: 31 33 34 5d 20 5b 48 31 32 31 33 37 5d 20 5b 48 134] [H12137] [H
3030: 31 32 31 33 38 5d 0a 2a 2f 0a 53 51 4c 49 54 45 12138].*/.SQLITE
3040: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
3050: 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 _exec(. sqlite3
3060: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 *,
3070: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3080: 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 /* An open d
3090: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e atabase */. con
30a0: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 st char *sql,
30b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
30c0: 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 /* SQL t
30d0: 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a o be evaluated *
30e0: 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 /. int (*callba
30f0: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 ck)(void*,int,ch
3100: 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f ar**,char**), /
3110: 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 * Callback funct
3120: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c ion */. void *,
3130: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3140: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3150: 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d /* 1st argum
3160: 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 ent to callback
3170: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d */. char **errm
3180: 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 sg
3190: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
31a0: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 /* Error msg wri
31b0: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a tten here */.);.
31c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
31d0: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 Result Codes {H
31e0: 31 30 32 31 30 7d 20 3c 53 31 30 37 30 30 3e 0a 10210} <S10700>.
31f0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c ** KEYWORDS: SQL
3200: 49 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f ITE_OK {error co
3210: 64 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 de} {error codes
3220: 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b }.** KEYWORDS: {
3230: 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 result code} {re
3240: 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a sult codes}.**.*
3250: 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 * Many SQLite fu
3260: 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 nctions return a
3270: 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 n integer result
3280: 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 code from the s
3290: 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 et shown.** here
32a0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 in order to ind
32b0: 69 63 61 74 65 73 20 73 75 63 63 65 73 73 20 6f icates success o
32c0: 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a r failure..**.**
32d0: 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 New error codes
32e0: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e may be added in
32f0: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 future versions
3300: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a of SQLite..**.*
3310: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c * See also: [SQL
3320: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c ITE_IOERR_READ |
3330: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 extended result
3340: 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69 codes].*/.#defi
3350: 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 ne SQLITE_OK
3360: 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 0 /* Su
3370: 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 ccessful result
3380: 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d */./* beginning-
3390: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a of-error-codes *
33a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
33b0: 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 _ERROR 1
33c0: 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f /* SQL error o
33d0: 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 r missing databa
33e0: 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 se */.#define SQ
33f0: 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 LITE_INTERNAL
3400: 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 2 /* Interna
3410: 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e l logic error in
3420: 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 SQLite */.#defi
3430: 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 ne SQLITE_PERM
3440: 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 3 /* Ac
3450: 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 cess permission
3460: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e denied */.#defin
3470: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 e SQLITE_ABORT
3480: 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 4 /* Cal
3490: 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 lback routine re
34a0: 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 quested an abort
34b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
34c0: 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 TE_BUSY
34d0: 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 5 /* The datab
34e0: 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b ase file is lock
34f0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ed */.#define SQ
3500: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 LITE_LOCKED
3510: 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 6 /* A table
3520: 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 in the database
3530: 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 is locked */.#d
3540: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d efine SQLITE_NOM
3550: 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a EM 7 /*
3560: 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c A malloc() fail
3570: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ed */.#define SQ
3580: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 LITE_READONLY
3590: 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 8 /* Attempt
35a0: 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 to write a read
35b0: 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f only database */
35c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
35d0: 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 INTERRUPT 9
35e0: 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 /* Operation te
35f0: 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 rminated by sqli
3600: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a te3_interrupt()*
3610: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
3620: 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 _IOERR 10
3630: 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f /* Some kind o
3640: 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 f disk I/O error
3650: 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 occurred */.#de
3660: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 fine SQLITE_CORR
3670: 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 UPT 11 /*
3680: 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 The database dis
3690: 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f k image is malfo
36a0: 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 rmed */.#define
36b0: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 SQLITE_NOTFOUND
36c0: 20 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55 12 /* NOT U
36d0: 53 45 44 2e 20 54 61 62 6c 65 20 6f 72 20 72 65 SED. Table or re
36e0: 63 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a cord not found *
36f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
3700: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 _FULL 13
3710: 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 /* Insertion f
3720: 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 ailed because da
3730: 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a tabase is full *
3740: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
3750: 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 _CANTOPEN 14
3760: 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f /* Unable to o
3770: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 pen the database
3780: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 file */.#define
3790: 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c SQLITE_PROTOCOL
37a0: 20 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20 15 /* NOT
37b0: 55 53 45 44 2e 20 44 61 74 61 62 61 73 65 20 6c USED. Database l
37c0: 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 ock protocol err
37d0: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 or */.#define SQ
37e0: 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 LITE_EMPTY
37f0: 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 16 /* Databas
3800: 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 e is empty */.#d
3810: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 efine SQLITE_SCH
3820: 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a EMA 17 /*
3830: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63 The database sc
3840: 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a hema changed */.
3850: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
3860: 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20 OOBIG 18
3870: 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f /* String or BLO
3880: 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c B exceeds size l
3890: 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 imit */.#define
38a0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
38b0: 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 T 19 /* Abort
38c0: 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 due to constrai
38d0: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a nt violation */.
38e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d #define SQLITE_M
38f0: 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 ISMATCH 20
3900: 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 /* Data type mis
3910: 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 match */.#define
3920: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 SQLITE_MISUSE
3930: 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 21 /* Libr
3940: 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 ary used incorre
3950: 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ctly */.#define
3960: 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 SQLITE_NOLFS
3970: 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 22 /* Uses
3980: 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 OS features not
3990: 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 supported on hos
39a0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
39b0: 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 ITE_AUTH
39c0: 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 23 /* Authoriz
39d0: 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a ation denied */.
39e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
39f0: 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 ORMAT 24
3a00: 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 /* Auxiliary dat
3a10: 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 abase format err
3a20: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 or */.#define SQ
3a30: 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 LITE_RANGE
3a40: 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 25 /* 2nd par
3a50: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
3a60: 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 3_bind out of ra
3a70: 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nge */.#define S
3a80: 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 QLITE_NOTADB
3a90: 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 26 /* File o
3aa0: 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f pened that is no
3ab0: 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c t a database fil
3ac0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e */.#define SQL
3ad0: 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 ITE_ROW
3ae0: 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 100 /* sqlite3_
3af0: 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 step() has anoth
3b00: 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a er row ready */.
3b10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
3b20: 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20 ONE 101
3b30: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 /* sqlite3_step(
3b40: 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 ) has finished e
3b50: 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 xecuting */./* e
3b60: 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 nd-of-error-code
3b70: 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 s */../*.** CAPI
3b80: 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 3REF: Extended R
3b90: 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 30 esult Codes {H10
3ba0: 32 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 220} <S10700>.**
3bb0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 KEYWORDS: {exte
3bc0: 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d nded error code}
3bd0: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 {extended error
3be0: 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f codes}.** KEYWO
3bf0: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 RDS: {extended r
3c00: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 esult code} {ext
3c10: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
3c20: 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 es}.**.** In its
3c30: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 default configu
3c40: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 ration, SQLite A
3c50: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 PI routines retu
3c60: 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 rn one of 26 int
3c70: 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f eger.** [SQLITE_
3c80: 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 OK | result code
3c90: 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 s]. However, ex
3ca0: 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f perience has sho
3cb0: 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a wn that many of.
3cc0: 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 ** these result
3cd0: 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f codes are too co
3ce0: 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 arse-grained. T
3cf0: 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 hey do not provi
3d00: 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e de as.** much in
3d10: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 formation about
3d20: 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 problems as prog
3d30: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 rammers might li
3d40: 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 ke. In an effor
3d50: 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 t to.** address
3d60: 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 this, newer vers
3d70: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 ions of SQLite (
3d80: 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e version 3.3.8 an
3d90: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 d later) include
3da0: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 .** support for
3db0: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c additional resul
3dc0: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f t codes that pro
3dd0: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c vide more detail
3de0: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a ed information.*
3df0: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 * about errors.
3e00: 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 The extended res
3e10: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e ult codes are en
3e20: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 abled or disable
3e30: 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 d.** on a per da
3e40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
3e50: 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 n basis using th
3e60: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 e.** [sqlite3_ex
3e70: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f tended_result_co
3e80: 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a des()] API..**.*
3e90: 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 * Some of the av
3ea0: 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 ailable extended
3eb0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 result codes ar
3ec0: 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a e listed here..*
3ed0: 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 * One may expect
3ee0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 the number of e
3ef0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
3f00: 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 odes will be exp
3f10: 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 and.** over time
3f20: 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 . Software that
3f30: 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 uses extended r
3f40: 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 esult codes shou
3f50: 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 ld expect.** to
3f60: 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 see new result c
3f70: 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 odes in future r
3f80: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 eleases of SQLit
3f90: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c e..**.** The SQL
3fa0: 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f ITE_OK result co
3fb0: 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 de will never be
3fc0: 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 extended. It w
3fd0: 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 ill always.** be
3fe0: 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a exactly zero..*
3ff0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4000: 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 _IOERR_READ
4010: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
4020: 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 _IOERR | (1<<8))
4030: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4040: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 IOERR_SHORT_READ
4050: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
4060: 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a IOERR | (2<<8)).
4070: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
4080: 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 OERR_WRITE
4090: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
40a0: 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 OERR | (3<<8)).#
40b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
40c0: 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 ERR_FSYNC
40d0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
40e0: 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 ERR | (4<<8)).#d
40f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
4100: 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 RR_DIR_FSYNC
4110: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
4120: 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 RR | (5<<8)).#de
4130: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
4140: 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 R_TRUNCATE
4150: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
4160: 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 R | (6<<8)).#def
4170: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
4180: 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20 _FSTAT
4190: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
41a0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 | (7<<8)).#defi
41b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
41c0: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 UNLOCK
41d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
41e0: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (8<<8)).#defin
41f0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 e SQLITE_IOERR_R
4200: 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 DLOCK
4210: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
4220: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (9<<8)).#define
4230: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 SQLITE_IOERR_DE
4240: 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 LETE
4250: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
4260: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (10<<8)).#define
4270: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c SQLITE_IOERR_BL
4280: 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 OCKED
4290: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
42a0: 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (11<<8)).#define
42b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f SQLITE_IOERR_NO
42c0: 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 MEM
42d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
42e0: 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (12<<8)).#define
42f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 SQLITE_IOERR_AC
4300: 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20 CESS
4310: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
4320: 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (13<<8)).#define
4330: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 SQLITE_IOERR_CH
4340: 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 ECKRESERVEDLOCK
4350: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
4360: 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (14<<8)).#define
4370: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f SQLITE_IOERR_LO
4380: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 CK
4390: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
43a0: 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (15<<8)).#define
43b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c SQLITE_IOERR_CL
43c0: 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20 OSE
43d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
43e0: 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (16<<8)).#define
43f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 SQLITE_IOERR_DI
4400: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 R_CLOSE
4410: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
4420: 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (17<<8)).#define
4430: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 SQLITE_LOCKED_S
4440: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 HAREDCACHE
4450: 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c (SQLITE_LOCKED |
4460: 20 28 31 3c 3c 38 29 20 29 0a 0a 2f 2a 0a 2a 2a (1<<8) )../*.**
4470: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 CAPI3REF: Flags
4480: 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f For File Open O
4490: 70 65 72 61 74 69 6f 6e 73 20 7b 48 31 30 32 33 perations {H1023
44a0: 30 7d 20 3c 48 31 31 31 32 30 3e 20 3c 48 31 32 0} <H11120> <H12
44b0: 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 700>.**.** These
44c0: 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 bit values are
44d0: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 intended for use
44e0: 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 in the.** 3rd p
44f0: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
4500: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
4510: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e ()] interface an
4520: 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 d.** in the 4th
4530: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
4540: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 xOpen method of
4550: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
4560: 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f _vfs] object..*/
4570: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4580: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 OPEN_READONLY
4590: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0x00000001
45a0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
45b0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
45c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
45d0: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 OPEN_READWRITE
45e0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0x00000002
45f0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
4600: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
4610: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4620: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 OPEN_CREATE
4630: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0x00000004
4640: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
4650: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
4660: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4670: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f OPEN_DELETEONCLO
4680: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38 SE 0x00000008
4690: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
46a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
46b0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 OPEN_EXCLUSIVE
46c0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0x00000010
46d0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
46e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
46f0: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 OPEN_MAIN_DB
4700: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0x00000100
4710: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
4720: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4730: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 OPEN_TEMP_DB
4740: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0x00000200
4750: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
4760: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4770: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 OPEN_TRANSIENT_D
4780: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 B 0x00000400
4790: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
47a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
47b0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 OPEN_MAIN_JOURNA
47c0: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30 L 0x00000800
47d0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
47e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
47f0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 OPEN_TEMP_JOURNA
4800: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30 L 0x00001000
4810: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
4820: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4830: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 OPEN_SUBJOURNAL
4840: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0x00002000
4850: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
4860: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4870: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 OPEN_MASTER_JOUR
4880: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 NAL 0x00004000
4890: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
48a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
48b0: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 OPEN_NOMUTEX
48c0: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30 0x00008000
48d0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
48e0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
48f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4900: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 OPEN_FULLMUTEX
4910: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30 0x00010000
4920: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
4930: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
4940: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4950: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 OPEN_SHAREDCACHE
4960: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30 0x00020000
4970: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
4980: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
4990: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
49a0: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 OPEN_PRIVATECACH
49b0: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30 E 0x00040000
49c0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
49d0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
49e0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
49f0: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74 : Device Charact
4a00: 65 72 69 73 74 69 63 73 20 7b 48 31 30 32 34 30 eristics {H10240
4a10: 7d 20 3c 48 31 31 31 32 30 3e 0a 2a 2a 0a 2a 2a } <H11120>.**.**
4a20: 20 54 68 65 20 78 44 65 76 69 63 65 43 61 70 61 The xDeviceCapa
4a30: 62 69 6c 69 74 69 65 73 20 6d 65 74 68 6f 64 20 bilities method
4a40: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
4a50: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f io_methods].** o
4a60: 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e bject returns an
4a70: 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 integer which i
4a80: 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 s a vector of th
4a90: 65 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 e these.** bit v
4aa0: 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 alues expressing
4ab0: 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 I/O characteris
4ac0: 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 tics of the mass
4ad0: 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 storage.** devi
4ae0: 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 ce that holds th
4af0: 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 e file that the
4b00: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
4b10: 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 ods].** refers t
4b20: 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c o..**.** The SQL
4b30: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
4b40: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 property means
4b50: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 that all writes
4b60: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 of.** any size a
4b70: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 re atomic. The
4b80: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
4b90: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a MICnnn values.**
4ba0: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 mean that write
4bb0: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 s of blocks that
4bc0: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 are nnn bytes i
4bd0: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 n size and.** ar
4be0: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 e aligned to an
4bf0: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 address which is
4c00: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 an integer mult
4c10: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 iple of.** nnn a
4c20: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 re atomic. The
4c30: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 SQLITE_IOCAP_SAF
4c40: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d E_APPEND value m
4c50: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 eans.** that whe
4c60: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 n data is append
4c70: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 ed to a file, th
4c80: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 e data is append
4c90: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e ed.** first then
4ca0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 the size of the
4cb0: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 file is extende
4cc0: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 d, never the oth
4cd0: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 er.** way around
4ce0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
4cf0: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 CAP_SEQUENTIAL p
4d00: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 roperty means th
4d10: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f at.** informatio
4d20: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 n is written to
4d30: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 disk in the same
4d40: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a order as calls.
4d50: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a ** to xWrite()..
4d60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4d70: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 E_IOCAP_ATOMIC
4d80: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
4d90: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 01.#define SQLIT
4da0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 E_IOCAP_ATOMIC51
4db0: 32 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 2 0x000000
4dc0: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 02.#define SQLIT
4dd0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b E_IOCAP_ATOMIC1K
4de0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
4df0: 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 04.#define SQLIT
4e00: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b E_IOCAP_ATOMIC2K
4e10: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
4e20: 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 08.#define SQLIT
4e30: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b E_IOCAP_ATOMIC4K
4e40: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
4e50: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 10.#define SQLIT
4e60: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b E_IOCAP_ATOMIC8K
4e70: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
4e80: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 20.#define SQLIT
4e90: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 E_IOCAP_ATOMIC16
4ea0: 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 K 0x000000
4eb0: 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 40.#define SQLIT
4ec0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 E_IOCAP_ATOMIC32
4ed0: 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 K 0x000000
4ee0: 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 80.#define SQLIT
4ef0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 E_IOCAP_ATOMIC64
4f00: 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 K 0x000001
4f10: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 00.#define SQLIT
4f20: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 E_IOCAP_SAFE_APP
4f30: 45 4e 44 20 20 20 20 20 30 78 30 30 30 30 30 32 END 0x000002
4f40: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 00.#define SQLIT
4f50: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 E_IOCAP_SEQUENTI
4f60: 41 4c 20 20 20 20 20 20 30 78 30 30 30 30 30 34 AL 0x000004
4f70: 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 00../*.** CAPI3R
4f80: 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 EF: File Locking
4f90: 20 4c 65 76 65 6c 73 20 7b 48 31 30 32 35 30 7d Levels {H10250}
4fa0: 20 3c 48 31 31 31 32 30 3e 20 3c 48 31 31 33 31 <H11120> <H1131
4fb0: 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 0>.**.** SQLite
4fc0: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 uses one of thes
4fd0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 e integer values
4fe0: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a as the second.*
4ff0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 * argument to ca
5000: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 lls it makes to
5010: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 the xLock() and
5020: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 xUnlock() method
5030: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 s.** of an [sqli
5040: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 te3_io_methods]
5050: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 object..*/.#defi
5060: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e ne SQLITE_LOCK_N
5070: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 ONE 0.#
5080: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f define SQLITE_LO
5090: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 CK_SHARED
50a0: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 1.#define SQLIT
50b0: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 E_LOCK_RESERVED
50c0: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 2.#define S
50d0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 QLITE_LOCK_PENDI
50e0: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 NG 3.#defi
50f0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 ne SQLITE_LOCK_E
5100: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a XCLUSIVE 4..
5110: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
5120: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 Synchronization
5130: 54 79 70 65 20 46 6c 61 67 73 20 7b 48 31 30 32 Type Flags {H102
5140: 36 30 7d 20 3c 48 31 31 31 32 30 3e 0a 2a 2a 0a 60} <H11120>.**.
5150: 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 ** When SQLite i
5160: 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 nvokes the xSync
5170: 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a () method of an.
5180: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d ** [sqlite3_io_m
5190: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 ethods] object i
51a0: 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 t uses a combina
51b0: 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 tion of.** these
51c0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 integer values
51d0: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 as the second ar
51e0: 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 gument..**.** Wh
51f0: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 en the SQLITE_SY
5200: 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 NC_DATAONLY flag
5210: 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 is used, it mea
5220: 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 ns that the.** s
5230: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e ync operation on
5240: 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 ly needs to flus
5250: 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 h data to mass s
5260: 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a torage. Inode.*
5270: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 * information ne
5280: 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 ed not be flushe
5290: 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 d. If the lower
52a0: 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 four bits of the
52b0: 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 flag.** equal S
52c0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 QLITE_SYNC_NORMA
52d0: 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f L, that means to
52e0: 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e use normal fsyn
52f0: 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a c() semantics..*
5300: 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 * If the lower f
5310: 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 our bits equal S
5320: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c QLITE_SYNC_FULL,
5330: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 that means.** t
5340: 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 o use Mac OS X s
5350: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e tyle fullsync in
5360: 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 stead of fsync()
5370: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
5380: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 ITE_SYNC_NORMAL
5390: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 0x00002.#
53a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 define SQLITE_SY
53b0: 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 NC_FULL
53c0: 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 0x00003.#define
53d0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 SQLITE_SYNC_DAT
53e0: 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 AONLY 0x000
53f0: 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 10../*.** CAPI3R
5400: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 EF: OS Interface
5410: 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c Open File Handl
5420: 65 20 7b 48 31 31 31 31 30 7d 20 3c 53 32 30 31 e {H11110} <S201
5430: 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 10>.**.** An [sq
5440: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 lite3_file] obje
5450: 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e ct represents an
5460: 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 open file in th
5470: 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 e .** [sqlite3_v
5480: 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 fs | OS interfac
5490: 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 e layer]. Indiv
54a0: 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 idual OS interfa
54b0: 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 ce.** implementa
54c0: 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 tions will.** wa
54d0: 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 nt to subclass t
54e0: 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 his object by ap
54f0: 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e pending addition
5500: 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 al fields.** for
5510: 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 their own use.
5520: 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e The pMethods en
5530: 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 try is a pointer
5540: 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 to an.** [sqlit
5550: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f e3_io_methods] o
5560: 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e bject that defin
5570: 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 es methods for p
5580: 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f erforming.** I/O
5590: 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 operations on t
55a0: 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f he open file..*/
55b0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
55c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c sqlite3_file sql
55d0: 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 ite3_file;.struc
55e0: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b t sqlite3_file {
55f0: 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 . const struct
5600: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
5610: 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f ds *pMethods; /
5620: 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e * Methods for an
5630: 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b open file */.};
5640: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
5650: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 : OS Interface F
5660: 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 ile Virtual Meth
5670: 6f 64 73 20 4f 62 6a 65 63 74 20 7b 48 31 31 31 ods Object {H111
5680: 32 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a 20} <S20110>.**.
5690: 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 ** Every file op
56a0: 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c ened by the [sql
56b0: 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20 ite3_vfs] xOpen
56c0: 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 method populates
56d0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f an.** [sqlite3_
56e0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 file] object (or
56f0: 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c , more commonly,
5700: 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 a subclass of t
5710: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 he.** [sqlite3_f
5720: 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 ile] object) wit
5730: 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 h a pointer to a
5740: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
5750: 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 is object..** Th
5760: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 is object define
5770: 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 s the methods us
5780: 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 ed to perform va
5790: 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 rious operations
57a0: 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 .** against the
57b0: 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 open file repres
57c0: 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 ented by the [sq
57d0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 lite3_file] obje
57e0: 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 ct..**.** If the
57f0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 73 65 xOpen method se
5800: 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 ts the sqlite3_f
5810: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 ile.pMethods ele
5820: 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f ment .** to a no
5830: 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 n-NULL pointer,
5840: 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 then the sqlite3
5850: 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f _io_methods.xClo
5860: 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 se method.** may
5870: 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e be invoked even
5880: 20 69 66 20 74 68 65 20 78 4f 70 65 6e 20 72 65 if the xOpen re
5890: 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66 ported that it f
58a0: 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f ailed. The.** o
58b0: 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 nly way to preve
58c0: 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c nt a call to xCl
58d0: 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 ose following a
58e0: 66 61 69 6c 65 64 20 78 4f 70 65 6e 0a 2a 2a 20 failed xOpen.**
58f0: 69 73 20 66 6f 72 20 74 68 65 20 78 4f 70 65 6e is for the xOpen
5900: 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 to set the sqli
5910: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 te3_file.pMethod
5920: 73 20 65 6c 65 6d 65 6e 74 20 74 6f 20 4e 55 4c s element to NUL
5930: 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 L..**.** The fla
5940: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 gs argument to x
5950: 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 Sync may be one
5960: 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f of [SQLITE_SYNC_
5970: 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 NORMAL] or.** [S
5980: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d QLITE_SYNC_FULL]
5990: 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f . The first cho
59a0: 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 ice is the norma
59b0: 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 l fsync()..** Th
59c0: 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 e second choice
59d0: 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 is a Mac OS X st
59e0: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 yle fullsync. T
59f0: 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f he [SQLITE_SYNC_
5a00: 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 DATAONLY].** fla
5a10: 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e g may be ORed in
5a20: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 to indicate tha
5a30: 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 t only the data
5a40: 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 of the file.** a
5a50: 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 nd not its inode
5a60: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e needs to be syn
5a70: 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 ced..**.** The i
5a80: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f nteger values to
5a90: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e xLock() and xUn
5aa0: 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f lock() are one o
5ab0: 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 f.** <ul>.** <li
5ac0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e > [SQLITE_LOCK_N
5ad0: 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 ONE],.** <li> [S
5ae0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 QLITE_LOCK_SHARE
5af0: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c D],.** <li> [SQL
5b00: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 ITE_LOCK_RESERVE
5b10: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c D],.** <li> [SQL
5b20: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 ITE_LOCK_PENDING
5b30: 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 ], or.** <li> [S
5b40: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 QLITE_LOCK_EXCLU
5b50: 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a SIVE]..** </ul>.
5b60: 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 ** xLock() incre
5b70: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 ases the lock. x
5b80: 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 Unlock() decreas
5b90: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 es the lock..**
5ba0: 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 The xCheckReserv
5bb0: 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 edLock() method
5bc0: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 checks whether a
5bd0: 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ny database conn
5be0: 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 ection,.** eithe
5bf0: 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 r in this proces
5c00: 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 s or in some oth
5c10: 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 er process, is h
5c20: 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 olding a RESERVE
5c30: 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f D,.** PENDING, o
5c40: 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b r EXCLUSIVE lock
5c50: 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 on the file. I
5c60: 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a t returns true.*
5c70: 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b * if such a lock
5c80: 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 exists and fals
5c90: 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a e otherwise..**.
5ca0: 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 ** The xFileCont
5cb0: 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 rol() method is
5cc0: 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 a generic interf
5cd0: 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 ace that allows
5ce0: 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d custom.** VFS im
5cf0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f plementations to
5d00: 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f directly contro
5d10: 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 l an open file u
5d20: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c sing the.** [sql
5d30: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
5d40: 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 l()] interface.
5d50: 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 The second "op"
5d60: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a argument is an.
5d70: 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 ** integer opcod
5d80: 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 e. The third ar
5d90: 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 gument is a gene
5da0: 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 ric pointer inte
5db0: 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 nded to.** point
5dc0: 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 to a structure
5dd0: 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e that may contain
5de0: 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 arguments or sp
5df0: 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a ace in which to.
5e00: 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 ** write return
5e10: 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 values. Potenti
5e20: 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c al uses for xFil
5e30: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 eControl() might
5e40: 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 be.** functions
5e50: 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b to enable block
5e60: 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 ing locks with t
5e70: 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e imeouts, to chan
5e80: 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e ge the.** lockin
5e90: 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 g strategy (for
5ea0: 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 example to use d
5eb0: 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 ot-file locks),
5ec0: 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 to inquire.** ab
5ed0: 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f out the status o
5ee0: 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 f a lock, or to
5ef0: 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b break stale lock
5f00: 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a s. The SQLite.*
5f10: 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 * core reserves
5f20: 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 all opcodes less
5f30: 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 than 100 for it
5f40: 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 s own use..** A
5f50: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f [SQLITE_FCNTL_LO
5f60: 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f CKSTATE | list o
5f70: 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 f opcodes] less
5f80: 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 than 100 is avai
5f90: 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 lable..** Applic
5fa0: 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 ations that defi
5fb0: 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c ne a custom xFil
5fc0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 eControl method
5fd0: 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 should use opcod
5fe0: 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 es.** greater th
5ff0: 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 an 100 to avoid
6000: 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a conflicts..**.**
6010: 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 The xSectorSize
6020: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e () method return
6030: 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a s the sector siz
6040: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 e of the.** devi
6050: 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 ce that underlie
6060: 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 s the file. The
6070: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 sector size is
6080: 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 the.** minimum w
6090: 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 rite that can be
60a0: 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f performed witho
60b0: 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a ut disturbing.**
60c0: 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 other bytes in
60d0: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 the file. The x
60e0: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 DeviceCharacteri
60f0: 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f stics().** metho
6100: 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 d returns a bit
6110: 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e vector describin
6120: 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 g behaviors of t
6130: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 he.** underlying
6140: 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c device:.**.** <
6150: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c ul>.** <li> [SQL
6160: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
6170: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
6180: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 E_IOCAP_ATOMIC51
6190: 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 2].** <li> [SQLI
61a0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 TE_IOCAP_ATOMIC1
61b0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
61c0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 TE_IOCAP_ATOMIC2
61d0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
61e0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 TE_IOCAP_ATOMIC4
61f0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
6200: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 TE_IOCAP_ATOMIC8
6210: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
6220: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 TE_IOCAP_ATOMIC1
6230: 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 6K].** <li> [SQL
6240: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
6250: 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 32K].** <li> [SQ
6260: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
6270: 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 C64K].** <li> [S
6280: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 QLITE_IOCAP_SAFE
6290: 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e _APPEND].** <li>
62a0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 [SQLITE_IOCAP_S
62b0: 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f EQUENTIAL].** </
62c0: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 ul>.**.** The SQ
62d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
62e0: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 C property means
62f0: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 that all writes
6300: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 of.** any size
6310: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 are atomic. The
6320: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
6330: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a OMICnnn values.*
6340: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 * mean that writ
6350: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 es of blocks tha
6360: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 t are nnn bytes
6370: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 in size and.** a
6380: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e re aligned to an
6390: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 address which i
63a0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c s an integer mul
63b0: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 tiple of.** nnn
63c0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 are atomic. The
63d0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 SQLITE_IOCAP_SA
63e0: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 FE_APPEND value
63f0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 means.** that wh
6400: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e en data is appen
6410: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 ded to a file, t
6420: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e he data is appen
6430: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 ded.** first the
6440: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 n the size of th
6450: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 e file is extend
6460: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 ed, never the ot
6470: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e her.** way aroun
6480: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 d. The SQLITE_I
6490: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 OCAP_SEQUENTIAL
64a0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 property means t
64b0: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 hat.** informati
64c0: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f on is written to
64d0: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d disk in the sam
64e0: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 e order as calls
64f0: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e .** to xWrite().
6500: 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 .**.** If xRead(
6510: 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 ) returns SQLITE
6520: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 _IOERR_SHORT_REA
6530: 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 D it must also f
6540: 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e ill.** in the un
6550: 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 read portions of
6560: 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68 the buffer with
6570: 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 zeros. A VFS t
6580: 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 hat.** fails to
6590: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 zero-fill short
65a0: 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d reads might seem
65b0: 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 to work. Howev
65c0: 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 er,.** failure t
65d0: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 o zero-fill shor
65e0: 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 t reads will eve
65f0: 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a ntually lead to.
6600: 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 ** database corr
6610: 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 uption..*/.typed
6620: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
6630: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 3_io_methods sql
6640: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b ite3_io_methods;
6650: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
6660: 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 io_methods {. i
6670: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 nt iVersion;. i
6680: 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c nt (*xClose)(sql
6690: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 ite3_file*);. i
66a0: 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 nt (*xRead)(sqli
66b0: 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a te3_file*, void*
66c0: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 , int iAmt, sqli
66d0: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 te3_int64 iOfst)
66e0: 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 ;. int (*xWrite
66f0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
6700: 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
6710: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f t iAmt, sqlite3_
6720: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 int64 iOfst);.
6730: 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 int (*xTruncate)
6740: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
6750: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 sqlite3_int64 si
6760: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 ze);. int (*xSy
6770: 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 nc)(sqlite3_file
6780: 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 *, int flags);.
6790: 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 int (*xFileSize
67a0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
67b0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a sqlite3_int64 *
67c0: 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a pSize);. int (*
67d0: 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 xLock)(sqlite3_f
67e0: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e ile*, int);. in
67f0: 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c t (*xUnlock)(sql
6800: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 ite3_file*, int)
6810: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b ;. int (*xCheck
6820: 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 ReservedLock)(sq
6830: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 lite3_file*, int
6840: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e *pResOut);. in
6850: 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c t (*xFileControl
6860: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
6870: 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 int op, void *p
6880: 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 Arg);. int (*xS
6890: 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 ectorSize)(sqlit
68a0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 e3_file*);. int
68b0: 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 (*xDeviceCharac
68c0: 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 teristics)(sqlit
68d0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 e3_file*);. /*
68e0: 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f Additional metho
68f0: 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 ds may be added
6900: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
6910: 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 es */.};../*.**
6920: 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 CAPI3REF: Standa
6930: 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 rd File Control
6940: 4f 70 63 6f 64 65 73 20 7b 48 31 31 33 31 30 7d Opcodes {H11310}
6950: 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S30800>.**.**
6960: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f These integer co
6970: 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f nstants are opco
6980: 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c des for the xFil
6990: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a eControl method.
69a0: 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ** of the [sqlit
69b0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f e3_io_methods] o
69c0: 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 bject and for th
69d0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f e [sqlite3_file_
69e0: 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e control()].** in
69f0: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 terface..**.** T
6a00: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
6a10: 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f _LOCKSTATE] opco
6a20: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 de is used for d
6a30: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a ebugging. This.
6a40: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 ** opcode causes
6a50: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f the xFileContro
6a60: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 l method to writ
6a70: 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 e the current st
6a80: 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f ate of.** the lo
6a90: 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 ck (one of [SQLI
6aa0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b TE_LOCK_NONE], [
6ab0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 SQLITE_LOCK_SHAR
6ac0: 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ED],.** [SQLITE_
6ad0: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 LOCK_RESERVED],
6ae0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e [SQLITE_LOCK_PEN
6af0: 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 DING], or [SQLIT
6b00: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 E_LOCK_EXCLUSIVE
6b10: 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e ]).** into an in
6b20: 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 teger that the p
6b30: 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 Arg argument poi
6b40: 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 nts to. This cap
6b50: 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 ability.** is us
6b60: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e ed during testin
6b70: 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 g and only needs
6b80: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 to be supported
6b90: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 when SQLITE_TES
6ba0: 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e T.** is defined.
6bb0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
6bc0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 TE_FCNTL_LOCKSTA
6bd0: 54 45 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 TE 1.#def
6be0: 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c ine SQLITE_GET_L
6bf0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 OCKPROXYFILE
6c00: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 2.#define SQLI
6c10: 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 TE_SET_LOCKPROXY
6c20: 46 49 4c 45 20 20 20 20 20 20 33 0a 23 64 65 66 FILE 3.#def
6c30: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f ine SQLITE_LAST_
6c40: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 ERRNO
6c50: 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 4../*.** CAPI3
6c60: 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c REF: Mutex Handl
6c70: 65 20 7b 48 31 37 31 31 30 7d 20 3c 53 32 30 31 e {H17110} <S201
6c80: 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 30>.**.** The mu
6c90: 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 tex module withi
6ca0: 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 n SQLite defines
6cb0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d [sqlite3_mutex]
6cc0: 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 to be an.** abs
6cd0: 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 tract type for a
6ce0: 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 mutex object.
6cf0: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 The SQLite core
6d00: 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 never looks.** a
6d10: 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 t the internal r
6d20: 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 epresentation of
6d30: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 an [sqlite3_mut
6d40: 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a ex]. It only.**
6d50: 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e deals with poin
6d60: 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c ters to the [sql
6d70: 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 ite3_mutex] obje
6d80: 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 ct..**.** Mutexe
6d90: 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 s are created us
6da0: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 ing [sqlite3_mut
6db0: 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a ex_alloc()]..*/.
6dc0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
6dd0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c qlite3_mutex sql
6de0: 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a ite3_mutex;../*.
6df0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 ** CAPI3REF: OS
6e00: 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 Interface Object
6e10: 20 7b 48 31 31 31 34 30 7d 20 3c 53 32 30 31 30 {H11140} <S2010
6e20: 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 0>.**.** An inst
6e30: 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 ance of the sqli
6e40: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 te3_vfs object d
6e50: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 efines the inter
6e60: 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 face between.**
6e70: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 the SQLite core
6e80: 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 and the underlyi
6e90: 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 ng operating sys
6ea0: 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a tem. The "vfs".
6eb0: 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f ** in the name o
6ec0: 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 f the object sta
6ed0: 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c nds for "virtual
6ee0: 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a file system"..*
6ef0: 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f *.** The value o
6f00: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 f the iVersion f
6f10: 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c ield is initiall
6f20: 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c y 1 but may be l
6f30: 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 arger in.** futu
6f40: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 re versions of S
6f50: 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e QLite. Addition
6f60: 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 al fields may be
6f70: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 appended to thi
6f80: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e s.** object when
6f90: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 the iVersion va
6fa0: 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 lue is increased
6fb0: 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 . Note that the
6fc0: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 structure.** of
6fd0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 the sqlite3_vfs
6fe0: 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 object changes
6ff0: 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 in the transacti
7000: 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 on between.** SQ
7010: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 Lite version 3.5
7020: 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 .9 and 3.6.0 and
7030: 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f yet the iVersio
7040: 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a n field was not.
7050: 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a ** modified..**.
7060: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 ** The szOsFile
7070: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a field is the siz
7080: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 e of the subclas
7090: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c sed [sqlite3_fil
70a0: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 e].** structure
70b0: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 used by this VFS
70c0: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 . mxPathname is
70d0: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e the maximum len
70e0: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 gth of.** a path
70f0: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 name in this VFS
7100: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 ..**.** Register
7110: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f ed sqlite3_vfs o
7120: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 bjects are kept
7130: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 on a linked list
7140: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 formed by.** th
7150: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e e pNext pointer.
7160: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 The [sqlite3_v
7170: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a fs_register()].*
7180: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 * and [sqlite3_v
7190: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d fs_unregister()]
71a0: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 interfaces mana
71b0: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 ge this list.**
71c0: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 in a thread-safe
71d0: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 way. The [sqli
71e0: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 te3_vfs_find()]
71f0: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 interface.** sea
7200: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 rches the list.
7210: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 Neither the app
7220: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f lication code no
7230: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 r the VFS.** imp
7240: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 lementation shou
7250: 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 ld use the pNext
7260: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 pointer..**.**
7270: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 The pNext field
7280: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c is the only fiel
7290: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 d in the sqlite3
72a0: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 _vfs.** structur
72b0: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 e that SQLite wi
72c0: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 ll ever modify.
72d0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c SQLite will onl
72e0: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d y access.** or m
72f0: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 odify this field
7300: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 while holding a
7310: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 particular stat
7320: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 ic mutex..** The
7330: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f application sho
7340: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 uld never modify
7350: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e anything within
7360: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 the sqlite3_vfs
7370: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 .** object once
7380: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 the object has b
7390: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a een registered..
73a0: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 **.** The zName
73b0: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 field holds the
73c0: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 name of the VFS
73d0: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d module. The nam
73e0: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 e must.** be uni
73f0: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 que across all V
7400: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a FS modules..**.*
7410: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67 75 * SQLite will gu
7420: 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 65 arantee that the
7430: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d zFilename param
7440: 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a eter to xOpen.**
7450: 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c is either a NUL
7460: 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 L pointer or str
7470: 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 ing obtained.**
7480: 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 from xFullPathna
7490: 6d 65 28 29 2e 20 20 53 51 4c 69 74 65 20 66 75 me(). SQLite fu
74a0: 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 rther guarantees
74b0: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 that.** the str
74c0: 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 ing will be vali
74d0: 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 d and unchanged
74e0: 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 until xClose() i
74f0: 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 s.** called. Bec
7500: 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 ause of the prev
7510: 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a ious sentence,.*
7520: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 * the [sqlite3_f
7530: 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 ile] can safely
7540: 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 store a pointer
7550: 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 to the.** filena
7560: 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 me if it needs t
7570: 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 o remember the f
7580: 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 ilename for some
7590: 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 reason..** If t
75a0: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 he zFilename par
75b0: 61 6d 65 74 65 72 20 69 73 20 78 4f 70 65 6e 20 ameter is xOpen
75c0: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
75d0: 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 r then xOpen.**
75e0: 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 must invent its
75f0: 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 own temporary na
7600: 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e me for the file.
7610: 20 20 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a Whenever the .
7620: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 ** xFilename par
7630: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 ameter is NULL i
7640: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 t will also be t
7650: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 he case that the
7660: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 .** flags parame
7670: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 ter will include
7680: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 [SQLITE_OPEN_DE
7690: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a LETEONCLOSE]..**
76a0: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 .** The flags ar
76b0: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 gument to xOpen(
76c0: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 ) includes all b
76d0: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 its set in.** th
76e0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 e flags argument
76f0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 to [sqlite3_ope
7700: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 n_v2()]. Or if
7710: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
7720: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f .** or [sqlite3_
7730: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 open16()] is use
7740: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e d, then flags in
7750: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a cludes at least.
7760: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ** [SQLITE_OPEN_
7770: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 READWRITE] | [SQ
7780: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
7790: 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 ]. .** If xOpen(
77a0: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 ) opens a file r
77b0: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 ead-only then it
77c0: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 sets *pOutFlags
77d0: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b to.** include [
77e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
77f0: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 ONLY]. Other bi
7800: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 ts in *pOutFlags
7810: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a may be set..**.
7820: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 ** SQLite will a
7830: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 lso add one of t
7840: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 he following fla
7850: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 gs to the xOpen(
7860: 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e ).** call, depen
7870: 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 ding on the obje
7880: 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a ct being opened:
7890: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
78a0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
78b0: 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c N_MAIN_DB].** <l
78c0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e i> [SQLITE_OPEN
78d0: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a _MAIN_JOURNAL].*
78e0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
78f0: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a OPEN_TEMP_DB].**
7900: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
7910: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c PEN_TEMP_JOURNAL
7920: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 ].** <li> [SQLI
7930: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e TE_OPEN_TRANSIEN
7940: 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b T_DB].** <li> [
7950: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a SQLITE_OPEN_SUBJ
7960: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 OURNAL].** <li>
7970: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 [SQLITE_OPEN_MA
7980: 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a STER_JOURNAL].**
7990: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 </ul>.**.** The
79a0: 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d file I/O implem
79b0: 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 entation can use
79c0: 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 the object type
79d0: 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 flags to.** cha
79e0: 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 nge the way it d
79f0: 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e eals with files.
7a00: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 For example, a
7a10: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a n application.**
7a20: 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 that does not c
7a30: 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 are about crash
7a40: 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c recovery or roll
7a50: 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a back might make.
7a60: 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 ** the open of a
7a70: 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 journal file a
7a80: 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 no-op. Writes t
7a90: 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 o this journal w
7aa0: 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 ould.** also be
7ab0: 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 no-ops, and any
7ac0: 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 attempt to read
7ad0: 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c the journal woul
7ae0: 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 d return.** SQLI
7af0: 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 TE_IOERR. Or th
7b00: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
7b10: 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 might recognize
7b20: 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 that a database
7b30: 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 .** file will be
7b40: 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 doing page-alig
7b50: 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 ned sector reads
7b60: 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 and writes in a
7b70: 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 random.** order
7b80: 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 and set up its
7b90: 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 I/O subsystem ac
7ba0: 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a cordingly..**.**
7bb0: 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c SQLite might al
7bc0: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 so add one of th
7bd0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 e following flag
7be0: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d s to the xOpen m
7bf0: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c ethod:.**.** <ul
7c00: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 >.** <li> [SQLIT
7c10: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 E_OPEN_DELETEONC
7c20: 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 LOSE].** <li> [S
7c30: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 QLITE_OPEN_EXCLU
7c40: 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a SIVE].** </ul>.*
7c50: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 *.** The [SQLITE
7c60: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c _OPEN_DELETEONCL
7c70: 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 OSE] flag means
7c80: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 the file should
7c90: 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 be.** deleted wh
7ca0: 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e en it is closed.
7cb0: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 The [SQLITE_OP
7cc0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 EN_DELETEONCLOSE
7cd0: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 ].** will be set
7ce0: 20 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61 62 for TEMP datab
7cf0: 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20 61 ases, journals a
7d00: 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e 61 nd for subjourna
7d10: 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 ls..**.** The [S
7d20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 QLITE_OPEN_EXCLU
7d30: 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c SIVE] flag is al
7d40: 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e ways used in con
7d50: 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 junction.** with
7d60: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 the [SQLITE_OPE
7d70: 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 N_CREATE] flag,
7d80: 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 which are both d
7d90: 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f irectly.** analo
7da0: 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 gous to the O_EX
7db0: 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 CL and O_CREAT f
7dc0: 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 lags of the POSI
7dd0: 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e X open().** API.
7de0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 The SQLITE_OPE
7df0: 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 N_EXCLUSIVE flag
7e00: 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 , when paired wi
7e10: 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 th the .** SQLIT
7e20: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 E_OPEN_CREATE, i
7e30: 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 s used to indica
7e40: 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f te that file sho
7e50: 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 uld always.** be
7e60: 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 created, and th
7e70: 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f at it is an erro
7e80: 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 r if it already
7e90: 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 exists..** It is
7ea0: 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 <i>not</i> used
7eb0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 to indicate the
7ec0: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 file should be
7ed0: 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 opened .** for e
7ee0: 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e xclusive access.
7ef0: 0a 2a 2a 0a 2a 2a 20 41 74 20 6c 65 61 73 74 20 .**.** At least
7f00: 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f szOsFile bytes o
7f10: 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c f memory are all
7f20: 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 ocated by SQLite
7f30: 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 .** to hold the
7f40: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 [sqlite3_file]
7f50: 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 structure passed
7f60: 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a as the third.**
7f70: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 argument to xOp
7f80: 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d en. The xOpen m
7f90: 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 ethod does not h
7fa0: 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 ave to.** alloca
7fb0: 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 te the structure
7fc0: 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 ; it should just
7fd0: 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f fill it in. No
7fe0: 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 te that.** the x
7ff0: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 Open method must
8000: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 set the sqlite3
8010: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 _file.pMethods t
8020: 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 o either.** a va
8030: 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f lid [sqlite3_io_
8040: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 methods] object
8050: 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 or to NULL. xOp
8060: 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 en must do.** th
8070: 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f is even if the o
8080: 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 pen fails. SQLi
8090: 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 te expects that
80a0: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 the sqlite3_file
80b0: 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 .pMethods.** ele
80c0: 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c ment will be val
80d0: 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 id after xOpen r
80e0: 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 eturns regardles
80f0: 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 s of the success
8100: 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f .** or failure o
8110: 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c f the xOpen call
8120: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 ..**.** The flag
8130: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 s argument to xA
8140: 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b ccess() may be [
8150: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 SQLITE_ACCESS_EX
8160: 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 ISTS].** to test
8170: 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e for the existen
8180: 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 ce of a file, or
8190: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f [SQLITE_ACCESS_
81a0: 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a READWRITE] to.**
81b0: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 test whether a
81c0: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 file is readable
81d0: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f and writable, o
81e0: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 r [SQLITE_ACCESS
81f0: 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 _READ].** to tes
8200: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 t whether a file
8210: 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 is at least rea
8220: 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c dable. The fil
8230: 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 e can be a.** di
8240: 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 53 rectory..**.** S
8250: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 QLite will alway
8260: 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 s allocate at le
8270: 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 ast mxPathname+1
8280: 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a bytes for the.*
8290: 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 * output buffer
82a0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 xFullPathname.
82b0: 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f The exact size o
82c0: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 f the output buf
82d0: 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 fer.** is also p
82e0: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d assed as a param
82f0: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 eter to both me
8300: 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 thods. If the ou
8310: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 tput buffer.** i
8320: 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 s not large enou
8330: 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 gh, [SQLITE_CANT
8340: 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 OPEN] should be
8350: 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 returned. Since
8360: 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c this is.** handl
8370: 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 ed as a fatal er
8380: 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 ror by SQLite, v
8390: 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f fs implementatio
83a0: 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 ns should endeav
83b0: 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 or.** to prevent
83c0: 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 this by setting
83d0: 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 mxPathname to a
83e0: 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 sufficiently la
83f0: 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a rge value..**.**
8400: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 The xRandomness
8410: 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 61 6e (), xSleep(), an
8420: 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 d xCurrentTime()
8430: 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 interfaces.** a
8440: 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 re not strictly
8450: 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 a part of the fi
8460: 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 lesystem, but th
8470: 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 ey are.** includ
8480: 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 ed in the VFS st
8490: 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 ructure for comp
84a0: 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 leteness..** The
84b0: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 xRandomness() f
84c0: 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 unction attempts
84d0: 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 to return nByte
84e0: 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f s bytes.** of go
84f0: 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f od-quality rando
8500: 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e mness into zOut.
8510: 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c The return val
8520: 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 ue is.** the act
8530: 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 ual number of by
8540: 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 tes of randomnes
8550: 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 s obtained..** T
8560: 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 he xSleep() meth
8570: 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 od causes the ca
8580: 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 lling thread to
8590: 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 sleep for at.**
85a0: 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 least the number
85b0: 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 of microseconds
85c0: 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43 75 given. The xCu
85d0: 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d rrentTime().** m
85e0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 ethod returns a
85f0: 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 Julian Day Numbe
8600: 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e r for the curren
8610: 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 2e t date and time.
8620: 0a 2a 2a 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 .**.*/.typedef s
8630: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 truct sqlite3_vf
8640: 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 73 s sqlite3_vfs;.s
8650: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 truct sqlite3_vf
8660: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 s {. int iVersi
8670: 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f on; /
8680: 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73 * Structure vers
8690: 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 ion number */.
86a0: 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 int szOsFile;
86b0: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 /* Size
86c0: 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 of subclassed s
86d0: 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 qlite3_file */.
86e0: 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b int mxPathname;
86f0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 /* Max
8700: 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 imum file pathna
8710: 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 me length */. s
8720: 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 qlite3_vfs *pNex
8730: 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 t; /* Next
8740: 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a registered VFS *
8750: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
8760: 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 zName; /*
8770: 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 Name of this vir
8780: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d tual file system
8790: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 */. void *pApp
87a0: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f Data; /
87b0: 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 * Pointer to app
87c0: 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 lication-specifi
87d0: 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 c data */. int
87e0: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 (*xOpen)(sqlite3
87f0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 _vfs*, const cha
8800: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 r *zName, sqlite
8810: 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 3_file*,.
8820: 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 int flag
8830: 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 s, int *pOutFlag
8840: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c s);. int (*xDel
8850: 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ete)(sqlite3_vfs
8860: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
8870: 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 Name, int syncDi
8880: 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 r);. int (*xAcc
8890: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ess)(sqlite3_vfs
88a0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
88b0: 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c Name, int flags,
88c0: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a int *pResOut);.
88d0: 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 int (*xFullPat
88e0: 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 hname)(sqlite3_v
88f0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 fs*, const char
8900: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 *zName, int nOut
8910: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 , char *zOut);.
8920: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e void *(*xDlOpen
8930: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
8940: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c const char *zFil
8950: 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 ename);. void (
8960: 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 *xDlError)(sqlit
8970: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 e3_vfs*, int nBy
8980: 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 te, char *zErrMs
8990: 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 g);. void (*(*x
89a0: 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 DlSym)(sqlite3_v
89b0: 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 fs*,void*, const
89c0: 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 char *zSymbol))
89d0: 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 (void);. void (
89e0: 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 *xDlClose)(sqlit
89f0: 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b e3_vfs*, void*);
8a00: 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d . int (*xRandom
8a10: 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 ness)(sqlite3_vf
8a20: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 s*, int nByte, c
8a30: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e har *zOut);. in
8a40: 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 t (*xSleep)(sqli
8a50: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 te3_vfs*, int mi
8a60: 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 croseconds);. i
8a70: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d nt (*xCurrentTim
8a80: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c e)(sqlite3_vfs*,
8a90: 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 double*);. int
8aa0: 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 (*xGetLastError
8ab0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
8ac0: 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 int, char *);.
8ad0: 2f 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 /* New fields ma
8ae0: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e y be appended in
8af0: 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 figure versions
8b00: 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a . The iVersion.
8b10: 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 ** value will
8b20: 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 increment whenev
8b30: 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e er this happens.
8b40: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.};../*.** CA
8b50: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f PI3REF: Flags fo
8b60: 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46 r the xAccess VF
8b70: 53 20 6d 65 74 68 6f 64 20 7b 48 31 31 31 39 30 S method {H11190
8b80: 7d 20 3c 48 31 31 31 34 30 3e 0a 2a 2a 0a 2a 2a } <H11140>.**.**
8b90: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 These integer c
8ba0: 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 onstants can be
8bb0: 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 used as the thir
8bc0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a d parameter to.*
8bd0: 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 * the xAccess me
8be0: 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 thod of an [sqli
8bf0: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e te3_vfs] object.
8c00: 20 7b 45 4e 44 7d 20 20 54 68 65 79 20 64 65 74 {END} They det
8c10: 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b ermine.** what k
8c20: 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f ind of permissio
8c30: 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d ns the xAccess m
8c40: 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 ethod is looking
8c50: 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 for..** With SQ
8c60: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 LITE_ACCESS_EXIS
8c70: 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 TS, the xAccess
8c80: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 method.** simply
8c90: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 checks whether
8ca0: 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e the file exists.
8cb0: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f .** With SQLITE_
8cc0: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 ACCESS_READWRITE
8cd0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 , the xAccess me
8ce0: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 thod.** checks w
8cf0: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 hether the file
8d00: 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 is both readable
8d10: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 0a 2a and writable..*
8d20: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 * With SQLITE_AC
8d30: 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 CESS_READ, the x
8d40: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a Access method.**
8d50: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 checks whether
8d60: 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 the file is read
8d70: 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 able..*/.#define
8d80: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 SQLITE_ACCESS_E
8d90: 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 XISTS 0.#defi
8da0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 ne SQLITE_ACCESS
8db0: 5f 52 45 41 44 57 52 49 54 45 20 31 0a 23 64 65 _READWRITE 1.#de
8dc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 fine SQLITE_ACCE
8dd0: 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 0a 0a SS_READ 2..
8de0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
8df0: 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 Initialize The S
8e00: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b 48 QLite Library {H
8e10: 31 30 31 33 30 7d 20 3c 53 32 30 30 30 30 3e 3c 10130} <S20000><
8e20: 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S30100>.**.** Th
8e30: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
8e40: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 lize() routine i
8e50: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a nitializes the.*
8e60: 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 * SQLite library
8e70: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 . The sqlite3_s
8e80: 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e hutdown() routin
8e90: 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 e.** deallocates
8ea0: 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 any resources t
8eb0: 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 hat were allocat
8ec0: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e ed by sqlite3_in
8ed0: 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 itialize()..** T
8ee0: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
8ef0: 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 e designed to ai
8f00: 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 d in process ini
8f10: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a tialization and.
8f20: 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 ** shutdown on e
8f30: 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e mbedded systems.
8f40: 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 Workstation ap
8f50: 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 plications using
8f60: 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 .** SQLite norma
8f70: 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 lly do not need
8f80: 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 to invoke either
8f90: 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e of these routin
8fa0: 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c es..**.** A call
8fb0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 to sqlite3_init
8fc0: 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 ialize() is an "
8fd0: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 effective" call
8fe0: 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 if it is.** the
8ff0: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 first time sqlit
9000: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
9010: 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e is invoked durin
9020: 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f g the lifetime o
9030: 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 f.** the process
9040: 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 , or if it is th
9050: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c e first time sql
9060: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
9070: 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 ) is invoked.**
9080: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c following a call
9090: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 to sqlite3_shut
90a0: 64 6f 77 6e 28 29 2e 20 20 4f 6e 6c 79 20 61 6e down(). Only an
90b0: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a effective call.
90c0: 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e ** of sqlite3_in
90d0: 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 itialize() does
90e0: 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 any initializati
90f0: 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 on. All other c
9100: 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d alls.** are harm
9110: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a less no-ops..**.
9120: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c ** A call to sql
9130: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 ite3_shutdown()
9140: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 is an "effective
9150: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 " call if it is
9160: 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c the first.** cal
9170: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 l to sqlite3_shu
9180: 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 tdown() since th
9190: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 e last sqlite3_i
91a0: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 4f 6e nitialize(). On
91b0: 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 ly.** an effecti
91c0: 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 ve call to sqlit
91d0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f e3_shutdown() do
91e0: 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c es any deinitial
91f0: 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 ization..** All
9200: 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c other valid call
9210: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 s to sqlite3_shu
9220: 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d tdown() are harm
9230: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a less no-ops..**.
9240: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 ** The sqlite3_i
9250: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 nitialize() inte
9260: 72 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73 rface is threads
9270: 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 afe, but sqlite3
9280: 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 _shutdown().** i
9290: 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 s not. The sqli
92a0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 te3_shutdown() i
92b0: 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e nterface must on
92c0: 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f ly be called fro
92d0: 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 m a.** single th
92e0: 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 read. All open
92f0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
9300: 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 tions] must be c
9310: 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a losed and all.**
9320: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 other SQLite re
9330: 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 sources must be
9340: 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f deallocated prio
9350: 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a r to invoking.**
9360: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
9370: 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 n()..**.** Among
9380: 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 73 other things, s
9390: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
93a0: 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a e() will invoke.
93b0: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e ** sqlite3_os_in
93c0: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 it(). Similarly
93d0: 2c 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f , sqlite3_shutdo
93e0: 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 wn().** will inv
93f0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 oke sqlite3_os_e
9400: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 nd()..**.** The
9410: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
9420: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 ze() routine ret
9430: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d urns [SQLITE_OK]
9440: 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 on success..**
9450: 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 If for some reas
9460: 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 on, sqlite3_init
9470: 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 ialize() is unab
9480: 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 le to initialize
9490: 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 .** the library
94a0: 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75 (perhaps it is u
94b0: 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 nable to allocat
94c0: 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 e a needed resou
94d0: 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 rce such.** as a
94e0: 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72 mutex) it retur
94f0: 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 ns an [error cod
9500: 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 e] other than [S
9510: 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a QLITE_OK]..**.**
9520: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 The sqlite3_ini
9530: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e tialize() routin
9540: 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 e is called inte
9550: 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f rnally by many o
9560: 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 ther.** SQLite i
9570: 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 nterfaces so tha
9580: 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e t an application
9590: 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f usually does no
95a0: 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 t need to.** inv
95b0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 oke sqlite3_init
95c0: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c ialize() directl
95d0: 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c y. For example,
95e0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
95f0: 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 ].** calls sqlit
9600: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
9610: 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 so the SQLite li
9620: 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 brary will be au
9630: 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 tomatically.** i
9640: 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 nitialized when
9650: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
9660: 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 is called if it
9670: 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 has not be init
9680: 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 ialized.** alrea
9690: 64 79 2e 20 20 48 6f 77 65 76 65 72 2c 20 69 66 dy. However, if
96a0: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
96b0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 led with the [SQ
96c0: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e LITE_OMIT_AUTOIN
96d0: 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 IT].** compile-t
96e0: 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e ime option, then
96f0: 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 the automatic c
9700: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
9710: 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 initialize().**
9720: 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 are omitted and
9730: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
9740: 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 must call sqlite
9750: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 3_initialize() d
9760: 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 irectly.** prior
9770: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 to using any ot
9780: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 her SQLite inter
9790: 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d face. For maxim
97a0: 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a um portability,.
97b0: 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 ** it is recomme
97c0: 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 nded that applic
97d0: 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e ations always in
97e0: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 voke sqlite3_ini
97f0: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 tialize().** dir
9800: 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 ectly prior to u
9810: 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 sing any other S
9820: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e QLite interface.
9830: 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 Future release
9840: 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d s.** of SQLite m
9850: 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e ay require this.
9860: 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 In other words
9870: 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 , the behavior e
9880: 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e xhibited.** when
9890: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
98a0: 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 led with [SQLITE
98b0: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 _OMIT_AUTOINIT]
98c0: 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 might become the
98d0: 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 .** default beha
98e0: 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 vior in some fut
98f0: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 ure release of S
9900: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 QLite..**.** The
9910: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
9920: 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 () routine does
9930: 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d operating-system
9940: 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 specific.** ini
9950: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 tialization of t
9960: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 he SQLite librar
9970: 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f y. The sqlite3_
9980: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 os_end().** rout
9990: 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 ine undoes the e
99a0: 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 ffect of sqlite3
99b0: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 _os_init(). Typ
99c0: 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 ical tasks.** pe
99d0: 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 rformed by these
99e0: 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 routines includ
99f0: 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 e allocation or
9a00: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 deallocation.**
9a10: 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 of static resour
9a20: 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 ces, initializat
9a30: 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 ion of global va
9a40: 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 riables,.** sett
9a50: 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 ing up a default
9a60: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d [sqlite3_vfs] m
9a70: 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e odule, or settin
9a80: 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c g up.** a defaul
9a90: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 t configuration
9aa0: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 using [sqlite3_c
9ab0: 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 onfig()]..**.**
9ac0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
9ad0: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 should never inv
9ae0: 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 oke either sqlit
9af0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 e3_os_init().**
9b00: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e or sqlite3_os_en
9b10: 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 d() directly. T
9b20: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 he application s
9b30: 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b hould only invok
9b40: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 e.** sqlite3_ini
9b50: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 tialize() and sq
9b60: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
9b70: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f . The sqlite3_o
9b80: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 s_init().** inte
9b90: 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 rface is called
9ba0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 automatically by
9bb0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
9bc0: 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c ize() and.** sql
9bd0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 ite3_os_end() is
9be0: 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 called by sqlit
9bf0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 e3_shutdown().
9c00: 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 Appropriate.** i
9c10: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 mplementations f
9c20: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e or sqlite3_os_in
9c30: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 it() and sqlite3
9c40: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 _os_end().** are
9c50: 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 built into SQLi
9c60: 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f te when it is co
9c70: 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c mpiled for Unix,
9c80: 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f Windows, or OS/
9c90: 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 2..** When [cust
9ca0: 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c om builds | buil
9cb0: 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 t for other plat
9cc0: 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 forms].** (using
9cd0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f the [SQLITE_OS_
9ce0: 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 OTHER=1] compile
9cf0: 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 -time.** option)
9d00: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
9d10: 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 must supply a s
9d20: 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e uitable implemen
9d30: 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 tation for.** sq
9d40: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 lite3_os_init()
9d50: 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 and sqlite3_os_e
9d60: 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 nd(). An applic
9d70: 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a ation-supplied.*
9d80: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
9d90: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 of sqlite3_os_i
9da0: 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 nit() or sqlite3
9db0: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 _os_end().** mus
9dc0: 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 t return [SQLITE
9dd0: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 _OK] on success
9de0: 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b and some other [
9df0: 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e error code] upon
9e00: 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a .** failure..*/.
9e10: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
9e20: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
9e30: 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f e(void);.SQLITE_
9e40: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
9e50: 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a shutdown(void);.
9e60: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
9e70: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 qlite3_os_init(v
9e80: 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 oid);.SQLITE_API
9e90: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f int sqlite3_os_
9ea0: 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a end(void);../*.*
9eb0: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 * CAPI3REF: Conf
9ec0: 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 iguring The SQLi
9ed0: 74 65 20 4c 69 62 72 61 72 79 20 7b 48 31 34 31 te Library {H141
9ee0: 30 30 7d 20 3c 53 32 30 30 30 30 3e 3c 53 33 30 00} <S20000><S30
9ef0: 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 200>.** EXPERIME
9f00: 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 NTAL.**.** The s
9f10: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
9f20: 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 interface is use
9f30: 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c d to make global
9f40: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a configuration.*
9f50: 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c * changes to SQL
9f60: 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 ite in order to
9f70: 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 tune SQLite to t
9f80: 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 he specific need
9f90: 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c s of.** the appl
9fa0: 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 ication. The de
9fb0: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 fault configurat
9fc0: 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 ion is recommend
9fd0: 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 ed for most.** a
9fe0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 pplications and
9ff0: 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 so this routine
a000: 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e is usually not n
a010: 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 ecessary. It is
a020: 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 .** provided to
a030: 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 support rare app
a040: 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 lications with u
a050: 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a nusual needs..**
a060: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
a070: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 config() interfa
a080: 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 ce is not thread
a090: 73 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 safe. The appli
a0a0: 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 cation.** must i
a0b0: 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 nsure that no ot
a0c0: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 her SQLite inter
a0d0: 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 faces are invoke
a0e0: 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 d by other.** th
a0f0: 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 reads while sqli
a100: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 te3_config() is
a110: 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 running. Furthe
a120: 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 rmore, sqlite3_c
a130: 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f onfig().** may o
a140: 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 nly be invoked p
a150: 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 rior to library
a160: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 initialization u
a170: 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 sing.** [sqlite3
a180: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f _initialize()] o
a190: 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e r after shutdown
a1a0: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 by [sqlite3_shu
a1b0: 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 4e 6f 74 tdown()]..** Not
a1c0: 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 e, however, that
a1d0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
a1e0: 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 ) can be called
a1f0: 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a as part of the.*
a200: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
a210: 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 of an applicati
a220: 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 on-defined [sqli
a230: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a te3_os_init()]..
a240: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
a250: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
a260: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 te3_config() is
a270: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 an integer.** [S
a280: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e QLITE_CONFIG_SIN
a290: 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 GLETHREAD | conf
a2a0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
a2b0: 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 ] that determine
a2c0: 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 s.** what proper
a2d0: 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 ty of SQLite is
a2e0: 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 to be configured
a2f0: 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 . Subsequent ar
a300: 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 guments.** vary
a310: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 depending on the
a320: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
a330: 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63 SINGLETHREAD | c
a340: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
a350: 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 ion].** in the f
a360: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a irst argument..*
a370: 2a 0a 2a 2a 20 57 68 65 6e 20 61 20 63 6f 6e 66 *.** When a conf
a380: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
a390: 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 is set, sqlite3
a3a0: 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e _config() return
a3b0: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a s [SQLITE_OK]..*
a3c0: 2a 20 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 * If the option
a3d0: 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 is unknown or SQ
a3e0: 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 Lite is unable t
a3f0: 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e o set the option
a400: 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f .** then this ro
a410: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 utine returns a
a420: 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 non-zero [error
a430: 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 code]..**.** Req
a440: 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
a450: 31 34 31 30 33 5d 20 5b 48 31 34 31 30 36 5d 20 14103] [H14106]
a460: 5b 48 31 34 31 32 30 5d 20 5b 48 31 34 31 32 33 [H14120] [H14123
a470: 5d 20 5b 48 31 34 31 32 36 5d 20 5b 48 31 34 31 ] [H14126] [H141
a480: 32 39 5d 20 5b 48 31 34 31 33 32 5d 20 5b 48 31 29] [H14132] [H1
a490: 34 31 33 35 5d 0a 2a 2a 20 5b 48 31 34 31 33 38 4135].** [H14138
a4a0: 5d 20 5b 48 31 34 31 34 31 5d 20 5b 48 31 34 31 ] [H14141] [H141
a4b0: 34 34 5d 20 5b 48 31 34 31 34 37 5d 20 5b 48 31 44] [H14147] [H1
a4c0: 34 31 35 30 5d 20 5b 48 31 34 31 35 33 5d 20 5b 4150] [H14153] [
a4d0: 48 31 34 31 35 36 5d 20 5b 48 31 34 31 35 39 5d H14156] [H14159]
a4e0: 0a 2a 2a 20 5b 48 31 34 31 36 32 5d 20 5b 48 31 .** [H14162] [H1
a4f0: 34 31 36 35 5d 20 5b 48 31 34 31 36 38 5d 0a 2a 4165] [H14168].*
a500: 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c /.SQLITE_API SQL
a510: 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c ITE_EXPERIMENTAL
a520: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e int sqlite3_con
a530: 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a fig(int, ...);..
a540: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
a550: 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 Configure databa
a560: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 20 se connections
a570: 7b 48 31 34 32 30 30 7d 20 3c 53 32 30 30 30 30 {H14200} <S20000
a580: 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 >.** EXPERIMENTA
a590: 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 L.**.** The sqli
a5a0: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 te3_db_config()
a5b0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 interface is use
a5c0: 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 d to make config
a5d0: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 uration.** chang
a5e0: 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 es to a [databas
a5f0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 e connection].
a600: 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 The interface is
a610: 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b similar to.** [
a620: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
a630: 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 ] except that th
a640: 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 e changes apply
a650: 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b to a single.** [
a660: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
a670: 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 ion] (specified
a680: 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 in the first arg
a690: 75 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a 20 ument). The.**
a6a0: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
a6b0: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 g() interface ca
a6c0: 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 69 n only be used i
a6d0: 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 mmediately after
a6e0: 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 .** the database
a6f0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 connection is c
a700: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 reated using [sq
a710: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a lite3_open()],.*
a720: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 * [sqlite3_open1
a730: 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 6()], or [sqlite
a740: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 0a 3_open_v2()]. .
a750: 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 **.** The second
a760: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c argument to sql
a770: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 ite3_db_config(D
a780: 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a ,V,...) is the.
a790: 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ** configuration
a7a0: 20 76 65 72 62 20 2d 20 61 6e 20 69 6e 74 65 67 verb - an integ
a7b0: 65 72 20 63 6f 64 65 20 74 68 61 74 20 69 6e 64 er code that ind
a7c0: 69 63 61 74 65 73 20 77 68 61 74 0a 2a 2a 20 61 icates what.** a
a7d0: 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 spect of the [da
a7e0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
a7f0: 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 n] is being conf
a800: 69 67 75 72 65 64 2e 0a 2a 2a 20 54 68 65 20 6f igured..** The o
a810: 6e 6c 79 20 63 68 6f 69 63 65 20 66 6f 72 20 74 nly choice for t
a820: 68 69 73 20 76 61 6c 75 65 20 69 73 20 5b 53 51 his value is [SQ
a830: 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f LITE_DBCONFIG_LO
a840: 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a 20 4e 65 77 OKASIDE]..** New
a850: 20 76 65 72 62 73 20 61 72 65 20 6c 69 6b 65 6c verbs are likel
a860: 79 20 74 6f 20 62 65 20 61 64 64 65 64 20 69 6e y to be added in
a870: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
a880: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 41 of SQLite..** A
a890: 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 dditional argume
a8a0: 6e 74 73 20 64 65 70 65 6e 64 20 6f 6e 20 74 68 nts depend on th
a8b0: 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 52 65 e verb..**.** Re
a8c0: 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
a8d0: 48 31 34 32 30 33 5d 20 5b 48 31 34 32 30 36 5d H14203] [H14206]
a8e0: 20 5b 48 31 34 32 30 39 5d 20 5b 48 31 34 32 31 [H14209] [H1421
a8f0: 32 5d 20 5b 48 31 34 32 31 35 5d 0a 2a 2f 0a 53 2] [H14215].*/.S
a900: 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
a910: 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e _EXPERIMENTAL in
a920: 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e t sqlite3_db_con
a930: 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e fig(sqlite3*, in
a940: 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a t op, ...);../*.
a950: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d ** CAPI3REF: Mem
a960: 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 ory Allocation R
a970: 6f 75 74 69 6e 65 73 20 7b 48 31 30 31 35 35 7d outines {H10155}
a980: 20 3c 53 32 30 31 32 30 3e 0a 2a 2a 20 45 58 50 <S20120>.** EXP
a990: 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 ERIMENTAL.**.**
a9a0: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 An instance of t
a9b0: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e his object defin
a9c0: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 es the interface
a9d0: 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a between SQLite.
a9e0: 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c ** and low-level
a9f0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
aa00: 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a on routines..**.
aa10: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 ** This object i
aa20: 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f s used in only o
aa30: 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 ne place in the
aa40: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
aa50: 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 ..** A pointer t
aa60: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 o an instance of
aa70: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 this object is
aa80: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a the argument to.
aa90: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ** [sqlite3_conf
aaa0: 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 ig()] when the c
aab0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
aac0: 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 ion is.** [SQLIT
aad0: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d E_CONFIG_MALLOC]
aae0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 or [SQLITE_CONF
aaf0: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 IG_GETMALLOC].
ab00: 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 .** By creating
ab10: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 an instance of t
ab20: 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e his object.** an
ab30: 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 d passing it to
ab40: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d [sqlite3_config]
ab50: 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f ([SQLITE_CONFIG_
ab60: 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 MALLOC]).** duri
ab70: 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ng configuration
ab80: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e , an application
ab90: 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 can specify an
aba0: 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d alternative.** m
abb0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
abc0: 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 subsystem for S
abd0: 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 QLite to use for
abe0: 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 all of its.** d
abf0: 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 ynamic memory ne
ac00: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 eds..**.** Note
ac10: 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 that SQLite come
ac20: 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b s with several [
ac30: 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 built-in memory
ac40: 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 allocators].** t
ac50: 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c hat are perfectl
ac60: 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 y adequate for t
ac70: 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 he overwhelming
ac80: 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c majority of appl
ac90: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 ications.** and
aca0: 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 that this object
acb0: 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 is only useful
acc0: 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 to a tiny minori
acd0: 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f ty of applicatio
ace0: 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 ns.** with speci
acf0: 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c alized memory al
ad00: 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 location require
ad10: 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a ments. This obj
ad20: 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 ect is.** also u
ad30: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 sed during testi
ad40: 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 ng of SQLite in
ad50: 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 order to specify
ad60: 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a an alternative.
ad70: 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ** memory alloca
ad80: 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 tor that simulat
ad90: 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 es memory out-of
ada0: 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f -memory conditio
adb0: 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 ns in.** order t
adc0: 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 o verify that SQ
add0: 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 Lite recovers gr
ade0: 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 acefully from su
adf0: 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 ch.** conditions
ae00: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c ..**.** The xMal
ae10: 6c 6f 63 20 61 6e 64 20 78 46 72 65 65 20 6d 65 loc and xFree me
ae20: 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 thods must work
ae30: 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c like the.** mall
ae40: 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 oc() and free()
ae50: 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 functions from t
ae60: 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 he standard C li
ae70: 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 20 78 52 brary..** The xR
ae80: 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 20 6d 75 ealloc method mu
ae90: 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 72 65 61 st work like rea
aea0: 6c 6c 6f 63 28 29 20 66 72 6f 6d 20 74 68 65 20 lloc() from the
aeb0: 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 standard C libra
aec0: 72 79 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 65 ry.** with the e
aed0: 78 63 65 70 74 69 6f 6e 20 74 68 61 74 20 69 66 xception that if
aee0: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
aef0: 6d 65 6e 74 20 74 6f 20 78 52 65 61 6c 6c 6f 63 ment to xRealloc
af00: 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 78 52 65 is zero,.** xRe
af10: 61 6c 6c 6f 63 20 6d 75 73 74 20 62 65 20 61 20 alloc must be a
af20: 6e 6f 2d 6f 70 20 2d 20 69 74 20 6d 75 73 74 20 no-op - it must
af30: 6e 6f 74 20 70 65 72 66 6f 72 6d 20 61 6e 79 20 not perform any
af40: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 0a 2a 2a allocation or.**
af50: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 deallocation.
af60: 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 SQLite guarantee
af70: 64 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f ds that the seco
af80: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a nd argument to.*
af90: 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c * xRealloc is al
afa0: 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 ways a value ret
afb0: 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 urned by a prior
afc0: 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 call to xRoundu
afd0: 70 2e 0a 2a 2a 20 41 6e 64 20 73 6f 20 69 6e 20 p..** And so in
afe0: 63 61 73 65 73 20 77 68 65 72 65 20 78 52 6f 75 cases where xRou
aff0: 6e 64 75 70 20 61 6c 77 61 79 73 20 72 65 74 75 ndup always retu
b000: 72 6e 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e rns a positive n
b010: 75 6d 62 65 72 2c 0a 2a 2a 20 78 52 65 61 6c 6c umber,.** xReall
b020: 6f 63 20 63 61 6e 20 70 65 72 66 6f 72 6d 20 65 oc can perform e
b030: 78 61 63 74 6c 79 20 61 73 20 74 68 65 20 73 74 xactly as the st
b040: 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79 20 72 andard library r
b050: 65 61 6c 6c 6f 63 28 29 20 61 6e 64 0a 2a 2a 20 ealloc() and.**
b060: 73 74 69 6c 6c 20 62 65 20 69 6e 20 63 6f 6d 70 still be in comp
b070: 6c 69 61 6e 63 65 20 77 69 74 68 20 74 68 69 73 liance with this
b080: 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a specification..
b090: 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 **.** xSize shou
b0a0: 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c ld return the al
b0b0: 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 located size of
b0c0: 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 a memory allocat
b0d0: 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c ion.** previousl
b0e0: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
b0f0: 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c xMalloc or xReal
b100: 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 loc. The alloca
b110: 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 ted size.** is a
b120: 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 lways at least a
b130: 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71 s big as the req
b140: 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 uested size but
b150: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a may be larger..*
b160: 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 *.** The xRoundu
b170: 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 p method returns
b180: 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 what would be t
b190: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a he allocated siz
b1a0: 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 e of.** a memory
b1b0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 allocation give
b1c0: 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 n a particular r
b1d0: 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 equested size.
b1e0: 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 Most memory.** a
b1f0: 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 llocators round
b200: 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 up memory alloca
b210: 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 tions at least t
b220: 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 o the next multi
b230: 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f ple.** of 8. So
b240: 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f me allocators ro
b250: 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 und up to a larg
b260: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 er multiple or t
b270: 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a o a power of 2..
b280: 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 ** Every memory
b290: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 allocation reque
b2a0: 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 st coming in thr
b2b0: 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 ough [sqlite3_ma
b2c0: 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 lloc()].** or [s
b2d0: 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
b2e0: 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 ] first calls xR
b2f0: 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 oundup. If xRou
b300: 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 ndup returns 0,
b310: 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 .** that causes
b320: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e the correspondin
b330: 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 g memory allocat
b340: 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a ion to fail..**.
b350: 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 ** The xInit met
b360: 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 hod initializes
b370: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 the memory alloc
b380: 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d ator. (For exam
b390: 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 ple,.** it might
b3a0: 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 allocate any re
b3b0: 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 quire mutexes or
b3c0: 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 initialize inte
b3d0: 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 rnal data.** str
b3e0: 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 uctures. The xS
b3f0: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 hutdown method i
b400: 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 s invoked (indir
b410: 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 ectly) by.** [sq
b420: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
b430: 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 ] and should dea
b440: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f llocate any reso
b450: 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a urces acquired.*
b460: 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 * by xInit. The
b470: 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 pAppData pointe
b480: 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 r is used as the
b490: 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 only parameter
b4a0: 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 to.** xInit and
b4b0: 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a xShutdown..**.**
b4c0: 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 SQLite holds th
b4d0: 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f e [SQLITE_MUTEX_
b4e0: 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d STATIC_MASTER] m
b4f0: 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 utex when it inv
b500: 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 okes.** the xIni
b510: 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 t method, so the
b520: 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 xInit method ne
b530: 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 ed not be thread
b540: 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 safe. The.** xS
b550: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 hutdown method i
b560: 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 s only called fr
b570: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 om [sqlite3_shut
b580: 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f down()] so it do
b590: 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 es.** not need t
b5a0: 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 o be threadsafe
b5b0: 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c either. For all
b5c0: 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 other methods,
b5d0: 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 SQLite.** holds
b5e0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 the [SQLITE_MUTE
b5f0: 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 X_STATIC_MEM] mu
b600: 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 tex as long as t
b610: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f he.** [SQLITE_CO
b620: 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 NFIG_MEMSTATUS]
b630: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
b640: 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f tion is turned o
b650: 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 n (which.** it i
b660: 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e s by default) an
b670: 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 d so the methods
b680: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c are automatical
b690: 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a ly serialized..*
b6a0: 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 * However, if [S
b6b0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d QLITE_CONFIG_MEM
b6c0: 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 STATUS] is disab
b6d0: 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 led, then the ot
b6e0: 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d her.** methods m
b6f0: 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 ust be threadsaf
b700: 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 e or else make t
b710: 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 heir own arrange
b720: 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 ments for.** ser
b730: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a ialization..**.*
b740: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 * SQLite will ne
b750: 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 ver invoke xInit
b760: 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 () more than onc
b770: 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 e without an int
b780: 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c ervening.** call
b790: 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e to xShutdown().
b7a0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
b7b0: 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d ct sqlite3_mem_m
b7c0: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d ethods sqlite3_m
b7d0: 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 em_methods;.stru
b7e0: 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d ct sqlite3_mem_m
b7f0: 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 ethods {. void
b800: 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 *(*xMalloc)(int)
b810: 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d ; /* Mem
b820: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 ory allocation f
b830: 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 unction */. voi
b840: 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a d (*xFree)(void*
b850: 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 ); /* F
b860: 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f ree a prior allo
b870: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 cation */. void
b880: 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f *(*xRealloc)(vo
b890: 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 id*,int); /* Re
b8a0: 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 size an allocati
b8b0: 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 on */. int (*xS
b8c0: 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 ize)(void*);
b8d0: 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e /* Return
b8e0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 the size of an
b8f0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 allocation */.
b900: 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 int (*xRoundup)(
b910: 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f int); /
b920: 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 * Round up reque
b930: 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 st size to alloc
b940: 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 ation size */.
b950: 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 int (*xInit)(voi
b960: 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f d*); /
b970: 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 * Initialize the
b980: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
b990: 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 r */. void (*xS
b9a0: 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b hutdown)(void*);
b9b0: 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 /* Deiniti
b9c0: 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 alize the memory
b9d0: 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 allocator */.
b9e0: 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 void *pAppData;
b9f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
ba00: 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 * Argument to xI
ba10: 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 nit() and xShutd
ba20: 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a own() */.};../*.
ba30: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e ** CAPI3REF: Con
ba40: 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f figuration Optio
ba50: 6e 73 20 7b 48 31 30 31 36 30 7d 20 3c 53 32 30 ns {H10160} <S20
ba60: 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 000>.** EXPERIME
ba70: 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 NTAL.**.** These
ba80: 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 constants are t
ba90: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 he available int
baa0: 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 eger configurati
bab0: 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a on options that.
bac0: 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 ** can be passed
bad0: 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 as the first ar
bae0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 gument to the [s
baf0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
bb00: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a interface..**.*
bb10: 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 * New configurat
bb20: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 ion options may
bb30: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 be added in futu
bb40: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 re releases of S
bb50: 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 QLite..** Existi
bb60: 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ng configuration
bb70: 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 options might b
bb80: 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 e discontinued.
bb90: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a Applications.**
bba0: 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 should check th
bbb0: 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 e return code fr
bbc0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 om [sqlite3_conf
bbd0: 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 ig()] to make su
bbe0: 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 re that.** the c
bbf0: 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 all worked. The
bc00: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
bc10: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 ()] interface wi
bc20: 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e ll return a.** n
bc30: 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 on-zero [error c
bc40: 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e ode] if a discon
bc50: 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 tinued or unsupp
bc60: 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 orted configurat
bc70: 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 ion option.** is
bc80: 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 invoked..**.**
bc90: 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 <dl>.** <dt>SQLI
bca0: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 TE_CONFIG_SINGLE
bcb0: 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c THREAD</dt>.** <
bcc0: 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 dd>There are no
bcd0: 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 arguments to thi
bce0: 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 s option. This
bcf0: 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a option disables.
bd00: 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 ** all mutexing
bd10: 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 and puts SQLite
bd20: 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 into a mode wher
bd30: 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 e it can only be
bd40: 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 used.** by a si
bd50: 6e 67 6c 65 20 74 68 72 65 61 64 2e 3c 2f 64 64 ngle thread.</dd
bd60: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
bd70: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 TE_CONFIG_MULTIT
bd80: 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 HREAD</dt>.** <d
bd90: 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 d>There are no a
bda0: 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 rguments to this
bdb0: 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f option. This o
bdc0: 70 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a ption disables.*
bdd0: 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 * mutexing on [d
bde0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
bdf0: 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 on] and [prepare
be00: 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a d statement] obj
be10: 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 ects..** The app
be20: 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 lication is resp
be30: 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 onsible for seri
be40: 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 alizing access t
be50: 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 o.** [database c
be60: 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 onnections] and
be70: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
be80: 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 ents]. But othe
be90: 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 r mutexes.** are
bea0: 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 enabled so that
beb0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 SQLite will be
bec0: 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 safe to use in a
bed0: 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a multi-threaded.
bee0: 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 ** environment a
bef0: 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f s long as no two
bf00: 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 threads attempt
bf10: 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 to use the same
bf20: 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
bf30: 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 nnection] at the
bf40: 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 53 65 65 same time. See
bf50: 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 the [threading
bf60: 6d 6f 64 65 5d 0a 2a 2a 20 64 6f 63 75 6d 65 6e mode].** documen
bf70: 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 tation for addit
bf80: 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f ional informatio
bf90: 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 n.</dd>.**.** <d
bfa0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
bfb0: 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a SERIALIZED</dt>.
bfc0: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 ** <dd>There are
bfd0: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f no arguments to
bfe0: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 this option. T
bff0: 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c his option enabl
c000: 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 es.** all mutexe
c010: 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 s including the
c020: 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 recursive.** mut
c030: 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 exes on [databas
c040: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e e connection] an
c050: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 d [prepared stat
c060: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a ement] objects..
c070: 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 ** In this mode
c080: 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 (which is the de
c090: 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 fault when SQLit
c0a0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
c0b0: 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 th.** [SQLITE_TH
c0c0: 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 READSAFE=1]) the
c0d0: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 SQLite library
c0e0: 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 will itself seri
c0f0: 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 alize access.**
c100: 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e to [database con
c110: 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 nections] and [p
c120: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
c130: 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a ts] so that the.
c140: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 ** application i
c150: 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 s free to use th
c160: 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 e same [database
c170: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 connection] or
c180: 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 the.** same [pre
c190: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
c1a0: 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 in different th
c1b0: 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d reads at the sam
c1c0: 65 20 74 69 6d 65 2e 0a 2a 2a 20 53 65 65 20 74 e time..** See t
c1d0: 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f he [threading mo
c1e0: 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f de] documentatio
c1f0: 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c n for additional
c200: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 64 information.</d
c210: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
c220: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f ITE_CONFIG_MALLO
c230: 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 C</dt>.** <dd>Th
c240: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 is option takes
c250: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
c260: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 t which is a poi
c270: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e nter to an.** in
c280: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 stance of the [s
c290: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
c2a0: 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 ds] structure.
c2b0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 The argument spe
c2c0: 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e cifies.** altern
c2d0: 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 ative low-level
c2e0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
c2f0: 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 n routines to be
c300: 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f used in place o
c310: 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 f.** the memory
c320: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 allocation routi
c330: 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 nes built into S
c340: 51 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a QLite.</dd>.**.*
c350: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
c360: 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 FIG_GETMALLOC</d
c370: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f t>.** <dd>This o
c380: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
c390: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 ngle argument wh
c3a0: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ich is a pointer
c3b0: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e to an.** instan
c3c0: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ce of the [sqlit
c3d0: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 e3_mem_methods]
c3e0: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 structure. The
c3f0: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 [sqlite3_mem_met
c400: 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 hods].** structu
c410: 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 re is filled wit
c420: 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 h the currently
c430: 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 defined memory a
c440: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e llocation routin
c450: 65 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 es..** This opti
c460: 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 on can be used t
c470: 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 o overload the d
c480: 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c efault memory al
c490: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 location.** rout
c4a0: 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 ines with a wrap
c4b0: 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 per that simulat
c4c0: 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ions memory allo
c4d0: 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f cation failure o
c4e0: 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f r.** tracks memo
c4f0: 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 ry usage, for ex
c500: 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a ample.</dd>.**.*
c510: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
c520: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 FIG_MEMSTATUS</d
c530: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f t>.** <dd>This o
c540: 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 ption takes sing
c550: 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 le argument of t
c560: 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 ype int, interpr
c570: 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f eted as a .** bo
c580: 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 olean, which ena
c590: 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 bles or disables
c5a0: 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 the collection
c5b0: 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 of memory alloca
c5c0: 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 tion .** statist
c5d0: 69 63 73 2e 20 57 68 65 6e 20 64 69 73 61 62 6c ics. When disabl
c5e0: 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e ed, the followin
c5f0: 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 g SQLite interfa
c600: 63 65 73 20 62 65 63 6f 6d 65 20 0a 2a 2a 20 6e ces become .** n
c610: 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a on-operational:.
c620: 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c ** <ul>.** <
c630: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d li> [sqlite3_mem
c640: 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 ory_used()].**
c650: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d <li> [sqlite3_m
c660: 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 emory_highwater(
c670: 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 )].** <li> [sq
c680: 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f lite3_soft_heap_
c690: 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 20 20 3c 6c limit()].** <l
c6a0: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 i> [sqlite3_stat
c6b0: 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e us()].** </ul>
c6c0: 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 .** </dd>.**.**
c6d0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
c6e0: 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a G_SCRATCH</dt>.*
c6f0: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f * <dd>This optio
c700: 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 n specifies a st
c710: 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 atic memory buff
c720: 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 er that SQLite c
c730: 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 an use for.** sc
c740: 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 ratch memory. T
c750: 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 here are three a
c760: 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 rguments: A poi
c770: 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a nter an 8-byte.*
c780: 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 * aligned memory
c790: 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 buffer from whi
c7a0: 63 68 20 74 68 65 20 73 63 72 61 63 68 20 61 6c ch the scrach al
c7b0: 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 locations will b
c7c0: 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 e.** drawn, the
c7d0: 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 size of each scr
c7e0: 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 atch allocation
c7f0: 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 (sz),.** and the
c800: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
c810: 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 of scratch alloc
c820: 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 ations (N). The
c830: 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 sz.** argument
c840: 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 must be a multip
c850: 6c 65 20 6f 66 20 31 36 2e 20 54 68 65 20 73 7a le of 16. The sz
c860: 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c parameter shoul
c870: 64 20 62 65 20 61 20 66 65 77 20 62 79 74 65 73 d be a few bytes
c880: 0a 2a 2a 20 6c 61 72 67 65 72 20 74 68 61 6e 20 .** larger than
c890: 74 68 65 20 61 63 74 75 61 6c 20 73 63 72 61 74 the actual scrat
c8a0: 63 68 20 73 70 61 63 65 20 72 65 71 75 69 72 65 ch space require
c8b0: 64 20 64 75 65 20 74 6f 20 69 6e 74 65 72 6e 61 d due to interna
c8c0: 6c 20 6f 76 65 72 68 65 61 64 2e 0a 2a 2a 20 54 l overhead..** T
c8d0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
c8e0: 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 65 72 t should pointer
c8f0: 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c to an 8-byte al
c900: 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 igned buffer.**
c910: 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e of at least sz*N
c920: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 bytes of memory
c930: 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c ..** SQLite will
c940: 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 use no more tha
c950: 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 n one scratch bu
c960: 66 66 65 72 20 61 74 20 6f 6e 63 65 20 70 65 72 ffer at once per
c970: 20 74 68 72 65 61 64 2c 20 73 6f 0a 2a 2a 20 4e thread, so.** N
c980: 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 should be set t
c990: 6f 20 74 68 65 20 65 78 70 65 63 74 65 64 20 6d o the expected m
c9a0: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
c9b0: 20 74 68 72 65 61 64 73 2e 20 20 54 68 65 20 73 threads. The s
c9c0: 7a 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 73 z.** parameter s
c9d0: 68 6f 75 6c 64 20 62 65 20 36 20 74 69 6d 65 73 hould be 6 times
c9e0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 the size of the
c9f0: 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73 largest databas
ca00: 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 e page size..**
ca10: 53 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 Scratch buffers
ca20: 61 72 65 20 75 73 65 64 20 61 73 20 70 61 72 74 are used as part
ca30: 20 6f 66 20 74 68 65 20 62 74 72 65 65 20 62 61 of the btree ba
ca40: 6c 61 6e 63 65 20 6f 70 65 72 61 74 69 6f 6e 2e lance operation.
ca50: 20 20 49 66 0a 2a 2a 20 54 68 65 20 62 74 72 65 If.** The btre
ca60: 65 20 62 61 6c 61 6e 63 65 72 20 6e 65 65 64 73 e balancer needs
ca70: 20 61 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f additional memo
ca80: 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 ry beyond what i
ca90: 73 20 70 72 6f 76 69 64 65 64 20 62 79 0a 2a 2a s provided by.**
caa0: 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73 scratch buffers
cab0: 20 6f 72 20 69 66 20 6e 6f 20 73 63 72 61 74 63 or if no scratc
cac0: 68 20 62 75 66 66 65 72 20 73 70 61 63 65 20 69 h buffer space i
cad0: 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 s specified, the
cae0: 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6f 65 73 n SQLite.** goes
caf0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c to [sqlite3_mal
cb00: 6c 6f 63 28 29 5d 20 74 6f 20 6f 62 74 61 69 6e loc()] to obtain
cb10: 20 74 68 65 20 6d 65 6d 6f 72 79 20 69 74 20 6e the memory it n
cb20: 65 65 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a eeds.</dd>.**.**
cb30: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
cb40: 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 IG_PAGECACHE</dt
cb50: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 >.** <dd>This op
cb60: 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 tion specifies a
cb70: 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 static memory b
cb80: 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 uffer that SQLit
cb90: 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a e can use for.**
cba0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 the database pa
cbb0: 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 ge cache with th
cbc0: 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 e default page c
cbd0: 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 61 74 69 ache implemenati
cbe0: 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f on. .** This co
cbf0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 nfiguration shou
cc00: 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 ld not be used i
cc10: 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e f an application
cc20: 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 -define page.**
cc30: 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 cache implementa
cc40: 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 tion is loaded u
cc50: 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f sing the SQLITE_
cc60: 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 6f 70 CONFIG_PCACHE op
cc70: 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 tion..** There a
cc80: 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e re three argumen
cc90: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f ts to this optio
cca0: 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 n: A pointer to
ccb0: 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 8-byte aligned.*
ccc0: 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 * memory, the si
ccd0: 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 ze of each page
cce0: 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 buffer (sz), and
ccf0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 the number of p
cd00: 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 ages (N)..** The
cd10: 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f sz argument sho
cd20: 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 uld be the size
cd30: 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 of the largest d
cd40: 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 atabase page.**
cd50: 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 (a power of two
cd60: 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 between 512 and
cd70: 33 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 32768) plus a li
cd80: 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 ttle extra for e
cd90: 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 ach.** page head
cda0: 65 72 2e 20 20 54 68 65 20 70 61 67 65 20 68 65 er. The page he
cdb0: 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 ader size is 20
cdc0: 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65 to 40 bytes depe
cdd0: 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 nding on.** the
cde0: 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72 host architectur
cdf0: 65 2e 20 20 49 74 20 69 73 20 68 61 72 6d 6c 65 e. It is harmle
ce00: 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 ss, apart from t
ce10: 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 he wasted memory
ce20: 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 ,.** to make sz
ce30: 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 a little too lar
ce40: 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a ge. The first.*
ce50: 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c * argument shoul
ce60: 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c d point to an al
ce70: 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c location of at l
ce80: 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 east sz*N bytes
ce90: 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 of memory..** SQ
cea0: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 Lite will use th
ceb0: 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 e memory provide
cec0: 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61 d by the first a
ced0: 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 rgument to satis
cee0: 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 fy its.** memory
cef0: 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 needs for the f
cf00: 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 irst N pages tha
cf10: 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 t it adds to cac
cf20: 68 65 2e 20 20 49 66 20 61 64 64 69 74 69 6f 6e he. If addition
cf30: 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 al.** page cache
cf40: 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 memory is neede
cf50: 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 d beyond what is
cf60: 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 provided by thi
cf70: 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a s option, then.*
cf80: 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f * SQLite goes to
cf90: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
cfa0: 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 ()] for the addi
cfb0: 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 tional storage s
cfc0: 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 69 6d 70 pace..** The imp
cfd0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 lementation migh
cfe0: 74 20 75 73 65 20 6f 6e 65 20 6f 72 20 6d 6f 72 t use one or mor
cff0: 65 20 6f 66 20 74 68 65 20 4e 20 62 75 66 66 65 e of the N buffe
d000: 72 73 20 74 6f 20 68 6f 6c 64 20 0a 2a 2a 20 6d rs to hold .** m
d010: 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 emory accounting
d020: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20 54 68 information. Th
d030: 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 e pointer in the
d040: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
d050: 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e must.** be align
d060: 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 ed to an 8-byte
d070: 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 boundary or subs
d080: 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 equent behavior
d090: 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c of SQLite.** wil
d0a0: 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c l be undefined.<
d0b0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
d0c0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 QLITE_CONFIG_HEA
d0d0: 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 P</dt>.** <dd>Th
d0e0: 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 is option specif
d0f0: 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d ies a static mem
d100: 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 ory buffer that
d110: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a SQLite will use.
d120: 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 ** for all of it
d130: 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 s dynamic memory
d140: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 allocation need
d150: 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 s beyond those p
d160: 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 rovided.** for b
d170: 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 y [SQLITE_CONFIG
d180: 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 _SCRATCH] and [S
d190: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 QLITE_CONFIG_PAG
d1a0: 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 ECACHE]..** Ther
d1b0: 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 e are three argu
d1c0: 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 ments: An 8-byte
d1d0: 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 aligned pointer
d1e0: 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a to the memory,.
d1f0: 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ** the number of
d200: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 bytes in the me
d210: 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 mory buffer, and
d220: 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c the minimum all
d230: 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a ocation size..**
d240: 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f If the first po
d250: 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 inter (the memor
d260: 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 y pointer) is NU
d270: 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 LL, then SQLite
d280: 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 reverts.** to us
d290: 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 ing its default
d2a0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
d2b0: 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c (the system mal
d2c0: 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 loc() implementa
d2d0: 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e tion),.** undoin
d2e0: 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f g any prior invo
d2f0: 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 cation of [SQLIT
d300: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d E_CONFIG_MALLOC]
d310: 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d . If the.** mem
d320: 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e ory pointer is n
d330: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 ot NULL and eith
d340: 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c er [SQLITE_ENABL
d350: 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a E_MEMSYS3] or.**
d360: 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f [SQLITE_ENABLE_
d370: 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 MEMSYS5] are def
d380: 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 ined, then the a
d390: 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 lternative memor
d3a0: 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 y.** allocator i
d3b0: 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e s engaged to han
d3c0: 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 dle all of SQLit
d3d0: 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 es memory alloca
d3e0: 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 tion needs..** T
d3f0: 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 he first pointer
d400: 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 (the memory poi
d410: 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c nter) must be al
d420: 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 igned to an 8-by
d430: 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f te.** boundary o
d440: 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 r subsequent beh
d450: 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 avior of SQLite
d460: 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 will be undefine
d470: 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 d.</dd>.**.** <d
d480: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
d490: 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 MUTEX</dt>.** <d
d4a0: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 d>This option ta
d4b0: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 kes a single arg
d4c0: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 ument which is a
d4d0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a pointer to an.*
d4e0: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 * instance of th
d4f0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 e [sqlite3_mutex
d500: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 _methods] struct
d510: 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 ure. The argume
d520: 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 nt specifies.**
d530: 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d alternative low-
d540: 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 level mutex rout
d550: 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 ines to be used
d560: 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 in place.** the
d570: 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 mutex routines b
d580: 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 uilt into SQLite
d590: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
d5a0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 >SQLITE_CONFIG_G
d5b0: 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 ETMUTEX</dt>.**
d5c0: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 <dd>This option
d5d0: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
d5e0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
d5f0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
d600: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 .** instance of
d610: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 the [sqlite3_mut
d620: 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 ex_methods] stru
d630: 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b cture. The.** [
d640: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 sqlite3_mutex_me
d650: 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 thods].** struct
d660: 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 ure is filled wi
d670: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 th the currently
d680: 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 defined mutex r
d690: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 outines..** This
d6a0: 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 option can be u
d6b0: 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 sed to overload
d6c0: 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 the default mute
d6d0: 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 x allocation.**
d6e0: 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 routines with a
d6f0: 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 wrapper used to
d700: 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 track mutex usag
d710: 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 e for performanc
d720: 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f e.** profiling o
d730: 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 r testing, for e
d740: 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a xample.</dd>.**.
d750: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ** <dt>SQLITE_CO
d760: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f NFIG_LOOKASIDE</
d770: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 dt>.** <dd>This
d780: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f option takes two
d790: 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 arguments that
d7a0: 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 determine the de
d7b0: 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 fault.** memory
d7c0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6c 6f 6f 6b 61 allocation looka
d7d0: 73 69 64 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f side optimizatio
d7e0: 6e 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 n. The first ar
d7f0: 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a gument is the.**
d800: 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f size of each lo
d810: 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 okaside buffer s
d820: 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f lot and the seco
d830: 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 nd is the number
d840: 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c of.** slots all
d850: 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 ocated to each d
d860: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
d870: 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e on. This option
d880: 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e sets the.** <i>
d890: 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b default</i> look
d8a0: 61 73 69 64 65 20 73 69 7a 65 2e 20 20 54 68 65 aside size. The
d8b0: 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 [SQLITE_DBCONFI
d8c0: 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 G_LOOKASIDE].**
d8d0: 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33 verb to [sqlite3
d8e0: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 _db_config()] ca
d8f0: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 n be used to cha
d900: 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 nge the lookasid
d910: 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 e.** configurati
d920: 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c on on individual
d930: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 3c 2f 64 connections.</d
d940: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
d950: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 ITE_CONFIG_PCACH
d960: 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 E</dt>.** <dd>Th
d970: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 is option takes
d980: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
d990: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 t which is a poi
d9a0: 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 nter to.** an [s
d9b0: 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 qlite3_pcache_me
d9c0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 thods] object.
d9d0: 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 This object spec
d9e0: 69 66 69 65 73 20 74 68 65 20 69 6e 74 65 72 66 ifies the interf
d9f0: 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 ace.** to a cust
da00: 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d om page cache im
da10: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 53 plementation. S
da20: 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f QLite makes a co
da30: 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a py of the.** obj
da40: 65 63 74 20 61 6e 64 20 75 73 65 73 20 69 74 20 ect and uses it
da50: 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d for page cache m
da60: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
da70: 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 s.</dd>.**.** <d
da80: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
da90: 47 45 54 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a GETPCACHE</dt>.*
daa0: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f * <dd>This optio
dab0: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
dac0: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 argument which
dad0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
dae0: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 an.** [sqlite3_p
daf0: 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f cache_methods] o
db00: 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 bject. SQLite c
db10: 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 opies of the cur
db20: 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 rent.** page cac
db30: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
db40: 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 n into that obje
db50: 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c ct.</dd>.**.** <
db60: 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 /dl>.*/.#define
db70: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 SQLITE_CONFIG_SI
db80: 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f NGLETHREAD 1 /
db90: 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 * nil */.#define
dba0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
dbb0: 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 ULTITHREAD 2
dbc0: 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e /* nil */.#defin
dbd0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
dbe0: 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 SERIALIZED 3
dbf0: 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 /* nil */.#defi
dc00: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
dc10: 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 _MALLOC 4
dc20: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d /* sqlite3_mem
dc30: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 _methods* */.#de
dc40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
dc50: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 IG_GETMALLOC
dc60: 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 5 /* sqlite3_m
dc70: 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 em_methods* */.#
dc80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
dc90: 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 NFIG_SCRATCH
dca0: 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 6 /* void*,
dcb0: 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f int sz, int N */
dcc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
dcd0: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 CONFIG_PAGECACHE
dce0: 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 7 /* void*
dcf0: 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 , int sz, int N
dd00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
dd10: 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 E_CONFIG_HEAP
dd20: 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 8 /* voi
dd30: 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 d*, int nByte, i
dd40: 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e nt min */.#defin
dd50: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
dd60: 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 MEMSTATUS 9
dd70: 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 /* boolean */.#
dd80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
dd90: 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 NFIG_MUTEX
dda0: 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 10 /* sqlite3
ddb0: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 _mutex_methods*
ddc0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
ddd0: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 E_CONFIG_GETMUTE
dde0: 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c X 11 /* sql
ddf0: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
de00: 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f ds* */./* previo
de10: 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 usly SQLITE_CONF
de20: 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 IG_CHUNKALLOC 12
de30: 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e which is now un
de40: 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e used. */ .#defin
de50: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
de60: 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 LOOKASIDE 13
de70: 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 /* int int */.#
de80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
de90: 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 NFIG_PCACHE
dea0: 20 20 31 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 14 /* sqlite3
deb0: 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a _pcache_methods*
dec0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
ded0: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 TE_CONFIG_GETPCA
dee0: 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 73 71 CHE 15 /* sq
def0: 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 lite3_pcache_met
df00: 68 6f 64 73 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 hods* */../*.**
df10: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 CAPI3REF: Config
df20: 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 uration Options
df30: 7b 48 31 30 31 37 30 7d 20 3c 53 32 30 30 30 30 {H10170} <S20000
df40: 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 >.** EXPERIMENTA
df50: 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f L.**.** These co
df60: 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 nstants are the
df70: 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 available intege
df80: 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 r configuration
df90: 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 options that.**
dfa0: 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 can be passed as
dfb0: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
dfc0: 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c ment to the [sql
dfd0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
dfe0: 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a ] interface..**.
dff0: 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 ** New configura
e000: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 tion options may
e010: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 be added in fut
e020: 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 ure releases of
e030: 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 SQLite..** Exist
e040: 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ing configuratio
e050: 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 n options might
e060: 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e be discontinued.
e070: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a Applications.*
e080: 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 * should check t
e090: 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 he return code f
e0a0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f rom [sqlite3_db_
e0b0: 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b config()] to mak
e0c0: 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 e sure that.** t
e0d0: 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 he call worked.
e0e0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 The [sqlite3_db
e0f0: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 _config()] inter
e100: 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e face will return
e110: 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b a.** non-zero [
e120: 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 error code] if a
e130: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 discontinued or
e140: 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e unsupported con
e150: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
e160: 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e n.** is invoked.
e170: 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c .**.** <dl>.** <
e180: 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 dt>SQLITE_DBCONF
e190: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 IG_LOOKASIDE</dt
e1a0: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 >.** <dd>This op
e1b0: 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 tion takes three
e1c0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 additional argu
e1d0: 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 ments that deter
e1e0: 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f mine the .** [lo
e1f0: 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 okaside memory a
e200: 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 llocator] config
e210: 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 uration for the
e220: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
e230: 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 tion]..** The fi
e240: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 rst argument (th
e250: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
e260: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 r to [sqlite3_db
e270: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a _config()] is a.
e280: 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e ** pointer to an
e290: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 memory buffer t
e2a0: 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 o use for lookas
e2b0: 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 54 ide memory..** T
e2c0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
e2d0: 74 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e t may be NULL in
e2e0: 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 which case SQLi
e2f0: 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 te will allocate
e300: 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 the.** lookasid
e310: 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 e buffer itself
e320: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d using [sqlite3_m
e330: 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 73 alloc()]. The s
e340: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 econd argument i
e350: 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 s the.** size of
e360: 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 each lookaside
e370: 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 buffer slot and
e380: 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 the third argume
e390: 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 nt is the number
e3a0: 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 of.** slots. T
e3b0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 he size of the b
e3c0: 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 uffer in the fir
e3d0: 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 st argument must
e3e0: 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e be greater than
e3f0: 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 .** or equal to
e400: 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 the product of t
e410: 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 he second and th
e420: 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 ird arguments.
e430: 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 The buffer.** mu
e440: 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f st be aligned to
e450: 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 an 8-byte bound
e460: 61 72 79 2e 20 20 49 66 20 74 68 65 20 73 65 63 ary. If the sec
e470: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ond argument is
e480: 6e 6f 74 0a 2a 2a 20 61 20 6d 75 6c 74 69 70 6c not.** a multipl
e490: 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e e of 8, it is in
e4a0: 74 65 72 6e 61 6c 6c 79 20 72 6f 75 6e 64 65 64 ternally rounded
e4b0: 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 down to the nex
e4c0: 74 20 73 6d 61 6c 6c 65 72 0a 2a 2a 20 6d 75 6c t smaller.** mul
e4d0: 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 53 65 65 tiple of 8. See
e4e0: 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 43 also: [SQLITE_C
e4f0: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d ONFIG_LOOKASIDE]
e500: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c </dd>.**.** </dl
e510: 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c >.*/.#define SQL
e520: 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
e530: 4b 41 53 49 44 45 20 20 20 20 31 30 30 31 20 20 KASIDE 1001
e540: 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 /* void* int int
e550: 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 */.../*.** CAPI
e560: 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 3REF: Enable Or
e570: 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 Disable Extended
e580: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 Result Codes {H
e590: 31 32 32 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 12200} <S10700>.
e5a0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
e5b0: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 3_extended_resul
e5c0: 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e t_codes() routin
e5d0: 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 e enables or dis
e5e0: 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 ables the.** [ex
e5f0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
e600: 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 des] feature of
e610: 53 51 4c 69 74 65 2e 20 54 68 65 20 65 78 74 65 SQLite. The exte
e620: 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 nded result.** c
e630: 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 odes are disable
e640: 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 d by default for
e650: 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 historical comp
e660: 61 74 69 62 69 6c 69 74 79 20 63 6f 6e 73 69 64 atibility consid
e670: 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 erations..**.**
e680: 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
e690: 20 5b 48 31 32 32 30 31 5d 20 5b 48 31 32 32 30 [H12201] [H1220
e6a0: 32 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 2].*/.SQLITE_API
e6b0: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 int sqlite3_ext
e6c0: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 ended_result_cod
e6d0: 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 es(sqlite3*, int
e6e0: 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 onoff);../*.**
e6f0: 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 CAPI3REF: Last I
e700: 6e 73 65 72 74 20 52 6f 77 69 64 20 7b 48 31 32 nsert Rowid {H12
e710: 32 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 220} <S10700>.**
e720: 0a 2a 2a 20 45 61 63 68 20 65 6e 74 72 79 20 69 .** Each entry i
e730: 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c n an SQLite tabl
e740: 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 e has a unique 6
e750: 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 4-bit signed.**
e760: 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c integer key call
e770: 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 ed the [ROWID |
e780: 22 72 6f 77 69 64 22 5d 2e 20 54 68 65 20 72 6f "rowid"]. The ro
e790: 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 wid is always av
e7a0: 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e ailable.** as an
e7b0: 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 undeclared colu
e7c0: 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 mn named ROWID,
e7d0: 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 OID, or _ROWID_
e7e0: 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 as long as those
e7f0: 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f .** names are no
e800: 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 t also used by e
e810: 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 xplicitly declar
e820: 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 49 66 0a 2a ed columns. If.*
e830: 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 * the table has
e840: 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 a column of type
e850: 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 [INTEGER PRIMAR
e860: 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 Y KEY] then that
e870: 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e column.** is an
e880: 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 other alias for
e890: 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a the rowid..**.**
e8a0: 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 This routine re
e8b0: 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 turns the [rowid
e8c0: 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 ] of the most re
e8d0: 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 cent.** successf
e8e0: 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f ul [INSERT] into
e8f0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72 the database fr
e900: 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 om the [database
e910: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 connection].**
e920: 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 in the first arg
e930: 75 6d 65 6e 74 2e 20 20 49 66 20 6e 6f 20 73 75 ument. If no su
e940: 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 ccessful [INSERT
e950: 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 ]s.** have ever
e960: 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74 occurred on that
e970: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
e980: 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 tion, zero is re
e990: 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 turned..**.** If
e9a0: 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 an [INSERT] occ
e9b0: 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 urs within a tri
e9c0: 67 67 65 72 2c 20 74 68 65 6e 20 74 68 65 20 5b gger, then the [
e9d0: 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e rowid] of the in
e9e0: 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 69 73 serted.** row is
e9f0: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 returned by thi
ea00: 73 20 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e s routine as lon
ea10: 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 g as the trigger
ea20: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 is running..**
ea30: 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 But once the tri
ea40: 67 67 65 72 20 74 65 72 6d 69 6e 61 74 65 73 2c gger terminates,
ea50: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
ea60: 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 ned by this rout
ea70: 69 6e 65 0a 2a 2a 20 72 65 76 65 72 74 73 20 74 ine.** reverts t
ea80: 6f 20 74 68 65 20 6c 61 73 74 20 76 61 6c 75 65 o the last value
ea90: 20 69 6e 73 65 72 74 65 64 20 62 65 66 6f 72 65 inserted before
eaa0: 20 74 68 65 20 74 72 69 67 67 65 72 20 66 69 72 the trigger fir
eab0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 49 4e ed..**.** An [IN
eac0: 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 SERT] that fails
ead0: 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 due to a constr
eae0: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 aint violation i
eaf0: 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 s not a.** succe
eb00: 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 ssful [INSERT] a
eb10: 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e nd does not chan
eb20: 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 ge the value ret
eb30: 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a urned by this.**
eb40: 20 72 6f 75 74 69 6e 65 2e 20 20 54 68 75 73 20 routine. Thus
eb50: 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 INSERT OR FAIL,
eb60: 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 INSERT OR IGNORE
eb70: 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c , INSERT OR ROLL
eb80: 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 BACK,.** and INS
eb90: 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b ERT OR ABORT mak
eba0: 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 e no changes to
ebb0: 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
ebc0: 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 of this.** rout
ebd0: 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 ine when their i
ebe0: 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 nsertion fails.
ebf0: 20 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 When INSERT OR
ec00: 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 REPLACE.** encou
ec10: 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 nters a constrai
ec20: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 nt violation, it
ec30: 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 does not fail.
ec40: 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 The.** INSERT c
ec50: 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 ontinues to comp
ec60: 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c letion after del
ec70: 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 eting rows that
ec80: 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f caused.** the co
ec90: 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d nstraint problem
eca0: 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 so INSERT OR RE
ecb0: 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 PLACE will alway
ecc0: 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 s change.** the
ecd0: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 return value of
ece0: 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a this interface..
ecf0: 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 **.** For the pu
ed00: 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 rposes of this r
ed10: 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 outine, an [INSE
ed20: 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 RT] is considere
ed30: 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 d to.** be succe
ed40: 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 ssful even if it
ed50: 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 is subsequently
ed60: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a rolled back..**
ed70: 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f .** This functio
ed80: 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 n is accessible
ed90: 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 to SQL statement
eda0: 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 s via the.** [la
edb0: 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 st_insert_rowid(
edc0: 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e ) SQL function].
edd0: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
ede0: 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 32 31 5d nts:.** [H12221]
edf0: 20 5b 48 31 32 32 32 33 5d 0a 2a 2a 0a 2a 2a 20 [H12223].**.**
ee00: 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 If a separate th
ee10: 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 read performs a
ee20: 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 new [INSERT] on
ee30: 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 the same.** data
ee40: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
ee50: 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 while the [sqlit
ee60: 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 e3_last_insert_r
ee70: 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 owid()].** funct
ee80: 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 ion is running a
ee90: 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 nd thus changes
eea0: 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 the last insert
eeb0: 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e [rowid],.** then
eec0: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
eed0: 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ned by [sqlite3_
eee0: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 last_insert_rowi
eef0: 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 d()] is.** unpre
ef00: 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 dictable and mig
ef10: 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 ht not equal eit
ef20: 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 her the old or t
ef30: 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 he new.** last i
ef40: 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a nsert [rowid]..*
ef50: 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c /.SQLITE_API sql
ef60: 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 ite3_int64 sqlit
ef70: 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 e3_last_insert_r
ef80: 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a owid(sqlite3*);.
ef90: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
efa0: 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 Count The Numbe
efb0: 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 r Of Rows Modifi
efc0: 65 64 20 7b 48 31 32 32 34 30 7d 20 3c 53 31 30 ed {H12240} <S10
efd0: 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 600>.**.** This
efe0: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
eff0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 the number of d
f000: 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 atabase rows tha
f010: 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a t were changed.*
f020: 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 * or inserted or
f030: 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 deleted by the
f040: 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f most recently co
f050: 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 mpleted SQL stat
f060: 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 ement.** on the
f070: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
f080: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 tion] specified
f090: 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72 by the first par
f0a0: 61 6d 65 74 65 72 2e 0a 2a 2a 20 4f 6e 6c 79 20 ameter..** Only
f0b0: 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 changes that are
f0c0: 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 directly specif
f0d0: 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45 ied by the [INSE
f0e0: 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a RT], [UPDATE],.*
f0f0: 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 * or [DELETE] st
f100: 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e atement are coun
f110: 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 ted. Auxiliary
f120: 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 changes caused b
f130: 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72 y.** triggers or
f140: 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 [foreign key ac
f150: 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 tions] are not c
f160: 6f 75 6e 74 65 64 2e 20 55 73 65 20 74 68 65 0a ounted. Use the.
f170: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 ** [sqlite3_tota
f180: 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e l_changes()] fun
f190: 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 ction to find th
f1a0: 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f e total number o
f1b0: 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 f changes.** inc
f1c0: 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 luding changes c
f1d0: 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72 aused by trigger
f1e0: 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 s and foreign ke
f1f0: 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a y actions..**.**
f200: 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 Changes to a vi
f210: 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 ew that are simu
f220: 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 lated by an [INS
f230: 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d TEAD OF trigger]
f240: 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e .** are not coun
f250: 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 ted. Only real
f260: 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 table changes ar
f270: 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a e counted..**.**
f280: 20 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 A "row change"
f290: 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 is a change to a
f2a0: 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 single row of a
f2b0: 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a single table.**
f2c0: 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e caused by an IN
f2d0: 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 SERT, DELETE, or
f2e0: 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e UPDATE statemen
f2f0: 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a t. Rows that.**
f300: 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 are changed as
f310: 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 side effects of
f320: 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 [REPLACE] constr
f330: 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c aint resolution,
f340: 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 .** rollback, AB
f350: 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 ORT processing,
f360: 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 [DROP TABLE], or
f370: 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a by any other.**
f380: 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e mechanisms do n
f390: 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 ot count as dire
f3a0: 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a ct row changes..
f3b0: 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72 **.** A "trigger
f3c0: 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73 context" is a s
f3d0: 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f cope of executio
f3e0: 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e n that begins an
f3f0: 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74 d.** ends with t
f400: 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 5b he script of a [
f410: 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c CREATE TRIGGER |
f420: 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d trigger]. .** M
f430: 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ost SQL statemen
f440: 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 ts are.** evalua
f450: 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61 ted outside of a
f460: 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69 ny trigger. Thi
f470: 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65 s is the "top le
f480: 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 vel".** trigger
f490: 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74 context. If a t
f4a0: 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f rigger fires fro
f4b0: 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c m the top level,
f4c0: 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 a.** new trigge
f4d0: 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 r context is ent
f4e0: 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72 ered for the dur
f4f0: 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e ation of that on
f500: 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53 e.** trigger. S
f510: 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74 ubtriggers creat
f520: 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f e subcontexts fo
f530: 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e r their duration
f540: 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 ..**.** Calling
f550: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
f560: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 or [sqlite3_ste
f570: 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79 p()] recursively
f580: 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 does.** not cre
f590: 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 65 ate a new trigge
f5a0: 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a r context..**.**
f5b0: 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 This function r
f5c0: 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
f5d0: 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 r of direct row
f5e0: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a changes in the.*
f5f0: 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e * most recent IN
f600: 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 SERT, UPDATE, or
f610: 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e DELETE statemen
f620: 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d t within the sam
f630: 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e e.** trigger con
f640: 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 75 73 text..**.** Thus
f650: 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 , when called fr
f660: 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c om the top level
f670: 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 , this function
f680: 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e returns the.** n
f690: 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 umber of changes
f6a0: 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 in the most rec
f6b0: 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 ent INSERT, UPDA
f6c0: 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a TE, or DELETE.**
f6d0: 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 that also occur
f6e0: 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c red at the top l
f6f0: 65 76 65 6c 2e 20 20 57 69 74 68 69 6e 20 74 68 evel. Within th
f700: 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 e body of a trig
f710: 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 ger,.** the sqli
f720: 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e te3_changes() in
f730: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 terface can be c
f740: 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 alled to find th
f750: 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 e number of.** c
f760: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f hanges in the mo
f770: 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 st recently comp
f780: 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 leted INSERT, UP
f790: 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a DATE, or DELETE.
f7a0: 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 ** statement wit
f7b0: 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 hin the body of
f7c0: 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 the same trigger
f7d0: 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 ..** However, th
f7e0: 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 e number returne
f7f0: 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 d does not inclu
f800: 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 de changes.** ca
f810: 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67 used by subtrigg
f820: 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 ers since those
f830: 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 have their own c
f840: 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 ontext..**.** Se
f850: 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 e also the [sqli
f860: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 te3_total_change
f870: 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 s()] interface,
f880: 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 the.** [count_ch
f890: 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 anges pragma], a
f8a0: 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 nd the [changes(
f8b0: 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e ) SQL function].
f8c0: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
f8d0: 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 34 31 5d nts:.** [H12241]
f8e0: 20 5b 48 31 32 32 34 33 5d 0a 2a 2a 0a 2a 2a 20 [H12243].**.**
f8f0: 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 If a separate th
f900: 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 read makes chang
f910: 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 es on the same d
f920: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
f930: 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c on.** while [sql
f940: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 ite3_changes()]
f950: 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 is running then
f960: 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
f970: 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 ed.** is unpredi
f980: 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d ctable and not m
f990: 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 eaningful..*/.SQ
f9a0: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
f9b0: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c ite3_changes(sql
f9c0: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ite3*);../*.** C
f9d0: 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e API3REF: Total N
f9e0: 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f umber Of Rows Mo
f9f0: 64 69 66 69 65 64 20 7b 48 31 32 32 36 30 7d 20 dified {H12260}
fa00: 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S10600>.**.** T
fa10: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 his function ret
fa20: 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
fa30: 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 of row changes c
fa40: 61 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54 aused by [INSERT
fa50: 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f ],.** [UPDATE] o
fa60: 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 r [DELETE] state
fa70: 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 ments since the
fa80: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
fa90: 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 tion] was opened
faa0: 2e 0a 2a 2a 20 54 68 65 20 63 6f 75 6e 74 20 69 ..** The count i
fab0: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e ncludes all chan
fac0: 67 65 73 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 ges from all [CR
fad0: 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 EATE TRIGGER | t
fae0: 72 69 67 67 65 72 5d 20 0a 2a 2a 20 63 6f 6e 74 rigger] .** cont
faf0: 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73 exts and changes
fb00: 20 6d 61 64 65 20 62 79 20 5b 66 6f 72 65 69 67 made by [foreig
fb10: 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 n key actions].
fb20: 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 However,.** the
fb30: 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 count does not i
fb40: 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 nclude changes u
fb50: 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 sed to implement
fb60: 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 [REPLACE] const
fb70: 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f raints,.** do ro
fb80: 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 llbacks or ABORT
fb90: 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 processing, or
fba0: 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f [DROP TABLE] pro
fbb0: 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a cessing. The.**
fbc0: 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 count does not
fbd0: 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 include rows of
fbe0: 76 69 65 77 73 20 74 68 61 74 20 66 69 72 65 20 views that fire
fbf0: 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 an [INSTEAD OF t
fc00: 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 rigger],.** thou
fc10: 67 68 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 gh if the INSTEA
fc20: 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b D OF trigger mak
fc30: 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 es changes of it
fc40: 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 s own, those cha
fc50: 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 nges .** are cou
fc60: 6e 74 65 64 2e 0a 2a 2a 20 54 68 65 20 63 68 61 nted..** The cha
fc70: 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 nges are counted
fc80: 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 as soon as the
fc90: 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d statement that m
fca0: 61 6b 65 73 20 74 68 65 6d 20 69 73 0a 2a 2a 20 akes them is.**
fcb0: 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 completed (when
fcc0: 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 the statement ha
fcd0: 6e 64 6c 65 20 69 73 20 70 61 73 73 65 64 20 74 ndle is passed t
fce0: 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 o [sqlite3_reset
fcf0: 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 ()] or.** [sqlit
fd00: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e e3_finalize()]).
fd10: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 .**.** See also
fd20: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 the [sqlite3_cha
fd30: 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 nges()] interfac
fd40: 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 e, the.** [count
fd50: 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d _changes pragma]
fd60: 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c , and the [total
fd70: 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 _changes() SQL f
fd80: 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 unction]..**.**
fd90: 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
fda0: 20 5b 48 31 32 32 36 31 5d 20 5b 48 31 32 32 36 [H12261] [H1226
fdb0: 33 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 3].**.** If a se
fdc0: 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 parate thread ma
fdd0: 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 kes changes on t
fde0: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 he same database
fdf0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 connection.** w
fe00: 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f hile [sqlite3_to
fe10: 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 tal_changes()] i
fe20: 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 s running then t
fe30: 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 he value.** retu
fe40: 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 rned is unpredic
fe50: 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 table and not me
fe60: 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c aningful..*/.SQL
fe70: 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
fe80: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 te3_total_change
fe90: 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a s(sqlite3*);../*
fea0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e .** CAPI3REF: In
feb0: 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 terrupt A Long-R
fec0: 75 6e 6e 69 6e 67 20 51 75 65 72 79 20 7b 48 31 unning Query {H1
fed0: 32 32 37 30 7d 20 3c 53 33 30 35 30 30 3e 0a 2a 2270} <S30500>.*
fee0: 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 *.** This functi
fef0: 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 on causes any pe
ff00: 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f nding database o
ff10: 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 peration to abor
ff20: 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 t and.** return
ff30: 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 at its earliest
ff40: 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 opportunity. Thi
ff50: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 s routine is typ
ff60: 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 ically.** called
ff70: 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 in response to
ff80: 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 a user action su
ff90: 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 ch as pressing "
ffa0: 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 Cancel".** or Ct
ffb0: 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 rl-C where the u
ffc0: 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 ser wants a long
ffd0: 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e query operation
ffe0: 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 to halt.** imme
fff0: 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 diately..**.** I
10000 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c t is safe to cal
10010 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 l this routine f
10020 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 rom a thread dif
10030 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a ferent from the.
10040 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 ** thread that i
10050 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e s currently runn
10060 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 ing the database
10070 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 operation. But
10080 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 it.** is not sa
10090 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 fe to call this
100a0 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b routine with a [
100b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
100c0 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 ion] that.** is
100d0 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 closed or might
100e0 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c close before sql
100f0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
10100 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 returns..**.**
10110 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 If an SQL operat
10120 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 ion is very near
10130 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 ly finished at t
10140 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 he time when.**
10150 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
10160 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 t() is called, t
10170 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 hen it might not
10180 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 have an opportu
10190 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e nity.** to be in
101a0 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 terrupted and mi
101b0 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 ght continue to
101c0 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a completion..**.*
101d0 2a 20 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 * An SQL operati
101e0 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 on that is inter
101f0 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 rupted will retu
10200 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 rn [SQLITE_INTER
10210 52 55 50 54 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 RUPT]..** If the
10220 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c interrupted SQL
10230 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e operation is an
10240 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c INSERT, UPDATE,
10250 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 or DELETE.** th
10260 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 at is inside an
10270 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 explicit transac
10280 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 tion, then the e
10290 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f ntire transactio
102a0 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c n.** will be rol
102b0 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 led back automat
102c0 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 ically..**.** Th
102d0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 e sqlite3_interr
102e0 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 upt(D) call is i
102f0 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 n effect until a
10300 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e ll currently run
10310 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 ning.** SQL stat
10320 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 ements on [datab
10330 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
10340 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 41 6e 79 D complete. Any
10350 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 new SQL stateme
10360 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 nts.** that are
10370 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 started after th
10380 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 e sqlite3_interr
10390 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 upt() call and b
103a0 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 efore the .** ru
103b0 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 nning statements
103c0 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 reaches zero ar
103d0 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 e interrupted as
103e0 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65 if they had bee
103f0 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 n.** running pri
10400 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 or to the sqlite
10410 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 3_interrupt() ca
10420 6c 6c 2e 20 20 4e 65 77 20 53 51 4c 20 73 74 61 ll. New SQL sta
10430 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 tements.** that
10440 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 are started afte
10450 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 r the running st
10460 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 atement count re
10470 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a aches zero are.*
10480 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 * not effected b
10490 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e y the sqlite3_in
104a0 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 41 20 terrupt()..** A
104b0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
104c0 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61 interrupt(D) tha
104d0 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 t occurs when th
104e0 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 ere are no runni
104f0 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d ng.** SQL statem
10500 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 ents is a no-op
10510 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 and has no effec
10520 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 t on SQL stateme
10530 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 nts.** that are
10540 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 started after th
10550 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 e sqlite3_interr
10560 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 upt() call retur
10570 6e 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 ns..**.** Requir
10580 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 ements:.** [H122
10590 37 31 5d 20 5b 48 31 32 32 37 32 5d 0a 2a 2a 0a 71] [H12272].**.
105a0 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 ** If the databa
105b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c se connection cl
105c0 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 oses while [sqli
105d0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d te3_interrupt()]
105e0 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 .** is running t
105f0 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 hen bad things w
10600 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 ill likely happe
10610 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 n..*/.SQLITE_API
10620 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e void sqlite3_in
10630 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a terrupt(sqlite3*
10640 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
10650 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 EF: Determine If
10660 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e An SQL Statemen
10670 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 20 7b 48 t Is Complete {H
10680 31 30 35 31 30 7d 20 3c 53 37 30 32 30 30 3e 0a 10510} <S70200>.
10690 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
106a0 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 ines are useful
106b0 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c during command-l
106c0 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 ine input to det
106d0 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a ermine if the.**
106e0 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 currently enter
106f0 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f ed text seems to
10700 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 form a complete
10710 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f SQL statement o
10720 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e r.** if addition
10730 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 al input is need
10740 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e ed before sendin
10750 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a g the text into.
10760 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 ** SQLite for pa
10770 72 73 69 6e 67 2e 20 20 54 68 65 73 65 20 72 6f rsing. These ro
10780 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 utines return 1
10790 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 if the input str
107a0 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 ing.** appears t
107b0 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 o be a complete
107c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 SQL statement.
107d0 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a A statement is j
107e0 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 udged to be.** c
107f0 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e omplete if it en
10800 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f ds with a semico
10810 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 lon token and is
10820 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 not a prefix of
10830 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 a.** well-forme
10840 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 d CREATE TRIGGER
10850 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 65 6d statement. Sem
10860 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 icolons that are
10870 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e embedded within
10880 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 .** string liter
10890 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 als or quoted id
108a0 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f entifier names o
108b0 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e r comments are n
108c0 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e ot.** independen
108d0 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 t tokens (they a
108e0 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 re part of the t
108f0 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 oken in which th
10900 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 ey are.** embedd
10910 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 ed) and thus do
10920 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 not count as a s
10930 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 tatement termina
10940 74 6f 72 2e 20 20 57 68 69 74 65 73 70 61 63 65 tor. Whitespace
10950 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 .** and comments
10960 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 that follow the
10970 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e final semicolon
10980 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a are ignored..**
10990 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
109a0 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 es return 0 if t
109b0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 he statement is
109c0 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 49 66 20 incomplete. If
109d0 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f a.** memory allo
109e0 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 cation fails, th
109f0 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 en SQLITE_NOMEM
10a00 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a is returned..**.
10a10 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
10a20 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 s do not parse t
10a30 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
10a40 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e s thus.** will n
10a50 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 ot detect syntac
10a60 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 tically incorrec
10a70 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 t SQL..**.** If
10a80 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 SQLite has not b
10a90 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 een initialized
10aa0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 using [sqlite3_i
10ab0 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 nitialize()] pri
10ac0 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 or .** to invoki
10ad0 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c ng sqlite3_compl
10ae0 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c ete16() then sql
10af0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
10b00 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 ) is invoked.**
10b10 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 automatically by
10b20 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 sqlite3_complet
10b30 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 e16(). If that
10b40 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 initialization f
10b50 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 ails,.** then th
10b60 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 e return value f
10b70 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 rom sqlite3_comp
10b80 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 lete16() will be
10b90 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 non-zero.** reg
10ba0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 ardless of wheth
10bb0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e er or not the in
10bc0 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c put SQL is compl
10bd0 65 74 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 ete..**.** Requi
10be0 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 35 31 31 rements: [H10511
10bf0 5d 20 5b 48 31 30 35 31 32 5d 0a 2a 2a 0a 2a 2a ] [H10512].**.**
10c00 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 The input to [s
10c10 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 qlite3_complete(
10c20 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 )] must be a zer
10c30 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 o-terminated.**
10c40 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a UTF-8 string..**
10c50 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f .** The input to
10c60 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 [sqlite3_comple
10c70 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 te16()] must be
10c80 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 a zero-terminate
10c90 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 d.** UTF-16 stri
10ca0 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 ng in native byt
10cb0 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49 e order..*/.SQLI
10cc0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
10cd0 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 e3_complete(cons
10ce0 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 53 51 t char *sql);.SQ
10cf0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
10d00 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 ite3_complete16(
10d10 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 const void *sql)
10d20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
10d30 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61 F: Register A Ca
10d40 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 llback To Handle
10d50 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 SQLITE_BUSY Err
10d60 6f 72 73 20 7b 48 31 32 33 31 30 7d 20 3c 53 34 ors {H12310} <S4
10d70 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 0400>.**.** This
10d80 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 routine sets a
10d90 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
10da0 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 n that might be
10db0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 invoked whenever
10dc0 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 .** an attempt i
10dd0 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 s made to open a
10de0 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 database table
10df0 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 that another thr
10e00 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 ead.** or proces
10e10 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a s has locked..**
10e20 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73 79 20 .** If the busy
10e30 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c callback is NULL
10e40 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 , then [SQLITE_B
10e50 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f USY] or [SQLITE_
10e60 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a IOERR_BLOCKED].*
10e70 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d * is returned im
10e80 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 mediately upon e
10e90 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 ncountering the
10ea0 6c 6f 63 6b 2e 20 49 66 20 74 68 65 20 62 75 73 lock. If the bus
10eb0 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 y callback.** is
10ec0 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 not NULL, then
10ed0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c the callback wil
10ee0 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 l be invoked wit
10ef0 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e h two arguments.
10f00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 .**.** The first
10f10 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
10f20 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f handler is a co
10f30 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 py of the void*
10f40 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a pointer which.**
10f50 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72 is the third ar
10f60 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 gument to sqlite
10f70 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 3_busy_handler()
10f80 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 . The second ar
10f90 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 gument to.** the
10fa0 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 handler callbac
10fb0 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 k is the number
10fc0 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 of times that th
10fd0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 e busy handler h
10fe0 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b as.** been invok
10ff0 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b ed for this lock
11000 69 6e 67 20 65 76 65 6e 74 2e 20 20 49 66 20 74 ing event. If t
11010 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 he.** busy callb
11020 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 ack returns 0, t
11030 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 hen no additiona
11040 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d l attempts are m
11050 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 ade to.** access
11060 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e the database an
11070 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 d [SQLITE_BUSY]
11080 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 or [SQLITE_IOERR
11090 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 _BLOCKED] is ret
110a0 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 urned..** If the
110b0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
110c0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e s non-zero, then
110d0 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 another attempt
110e0 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f .** is made to o
110f0 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 pen the database
11100 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 for reading and
11110 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 the cycle repea
11120 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 ts..**.** The pr
11130 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 esence of a busy
11140 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f handler does no
11150 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 t guarantee that
11160 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f it will be invo
11170 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 ked.** when ther
11180 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e e is lock conten
11190 74 69 6f 6e 2e 20 49 66 20 53 51 4c 69 74 65 20 tion. If SQLite
111a0 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 determines that
111b0 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 invoking the bus
111c0 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 y.** handler cou
111d0 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 ld result in a d
111e0 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c eadlock, it will
111f0 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 go ahead and re
11200 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 turn [SQLITE_BUS
11210 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 Y].** or [SQLITE
11220 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 _IOERR_BLOCKED]
11230 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b instead of invok
11240 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e ing the busy han
11250 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 dler..** Conside
11260 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 r a scenario whe
11270 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 re one process i
11280 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 s holding a read
11290 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 lock that.** it
112a0 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 is trying to pr
112b0 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 omote to a reser
112c0 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 ved lock and.**
112d0 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 a second process
112e0 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 is holding a re
112f0 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 served lock that
11300 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a it is trying.**
11310 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 to promote to a
11320 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b n exclusive lock
11330 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f . The first pro
11340 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 cess cannot proc
11350 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 eed.** because i
11360 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 t is blocked by
11370 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 the second and t
11380 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 he second proces
11390 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 s cannot.** proc
113a0 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 eed because it i
113b0 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 s blocked by the
113c0 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 first. If both
113d0 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e processes.** in
113e0 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 voke the busy ha
113f0 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 ndlers, neither
11400 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 will make any pr
11410 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f ogress. Therefo
11420 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 re,.** SQLite re
11430 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 turns [SQLITE_BU
11440 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 SY] for the firs
11450 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e t process, hopin
11460 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 g that this.** w
11470 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 ill induce the f
11480 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 irst process to
11490 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 release its read
114a0 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a lock and allow.
114b0 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 ** the second pr
114c0 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 ocess to proceed
114d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 ..**.** The defa
114e0 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 ult busy callbac
114f0 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a k is NULL..**.**
11500 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 The [SQLITE_BUS
11510 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 Y] error is conv
11520 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 erted to [SQLITE
11530 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a _IOERR_BLOCKED].
11540 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 ** when SQLite i
11550 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 s in the middle
11560 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 of a large trans
11570 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c action where all
11580 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 the.** changes
11590 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 will not fit int
115a0 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 o the in-memory
115b0 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 cache. SQLite w
115c0 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 ill.** already h
115d0 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c old a RESERVED l
115e0 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 ock on the datab
115f0 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 ase file, but it
11600 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f needs.** to pro
11610 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 mote this lock t
11620 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 o EXCLUSIVE so t
11630 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c hat it can spill
11640 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 cache.** pages
11650 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 into the databas
11660 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 e file without h
11670 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e arm to concurren
11680 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 49 t.** readers. I
11690 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 f it is unable t
116a0 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f o promote the lo
116b0 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d ck, then the in-
116c0 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 memory.** cache
116d0 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 will be left in
116e0 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 an inconsistent
116f0 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 state and so the
11700 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 error.** code i
11710 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 s promoted from
11720 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 the relatively b
11730 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 enign [SQLITE_BU
11740 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f SY] to.** the mo
11750 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 re severe [SQLIT
11760 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d E_IOERR_BLOCKED]
11770 2e 20 20 54 68 69 73 20 65 72 72 6f 72 20 63 6f . This error co
11780 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 de promotion.**
11790 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 forces an automa
117a0 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 tic rollback of
117b0 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 the changes. Se
117c0 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 e the.** <a href
117d0 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f ="/cvstrac/wiki?
117e0 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c p=CorruptionFoll
117f0 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e owingBusyError">
11800 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f .** CorruptionFo
11810 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 llowingBusyError
11820 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 </a> wiki page f
11830 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 or a discussion
11840 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 of why.** this i
11850 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a s important..**.
11860 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c ** There can onl
11870 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 y be a single bu
11880 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e sy handler defin
11890 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b ed for each.** [
118a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
118b0 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 ion]. Setting a
118c0 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 new busy handle
118d0 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 r clears any.**
118e0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 previously set h
118f0 61 6e 64 6c 65 72 2e 20 20 4e 6f 74 65 20 74 68 andler. Note th
11900 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 at calling [sqli
11910 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 te3_busy_timeout
11920 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f ()].** will also
11930 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 set or clear th
11940 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a e busy handler..
11950 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 **.** The busy c
11960 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e allback should n
11970 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 ot take any acti
11980 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 ons which modify
11990 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 the.** database
119a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 connection that
119b0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 invoked the bus
119c0 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 y handler. Any
119d0 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 such actions.**
119e0 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 result in undefi
119f0 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a ned behavior..**
11a00 20 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 .** Requirement
11a10 73 3a 0a 2a 2a 20 5b 48 31 32 33 31 31 5d 20 5b s:.** [H12311] [
11a20 48 31 32 33 31 32 5d 20 5b 48 31 32 33 31 34 5d H12312] [H12314]
11a30 20 5b 48 31 32 33 31 36 5d 20 5b 48 31 32 33 31 [H12316] [H1231
11a40 38 5d 0a 2a 2a 0a 2a 2a 20 41 20 62 75 73 79 20 8].**.** A busy
11a50 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 handler must not
11a60 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 close the datab
11a70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase connection.*
11a80 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 * or [prepared s
11a90 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 tatement] that i
11aa0 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 nvoked the busy
11ab0 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 handler..*/.SQLI
11ac0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
11ad0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 e3_busy_handler(
11ae0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 sqlite3*, int(*)
11af0 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 (void*,int), voi
11b00 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 d*);../*.** CAPI
11b10 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 3REF: Set A Busy
11b20 20 54 69 6d 65 6f 75 74 20 7b 48 31 32 33 34 30 Timeout {H12340
11b30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a } <S40410>.**.**
11b40 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 This routine se
11b50 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 ts a [sqlite3_bu
11b60 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 sy_handler | bus
11b70 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 y handler] that
11b80 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 sleeps.** for a
11b90 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 specified amount
11ba0 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 of time when a
11bb0 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e table is locked.
11bc0 20 20 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a The handler.**
11bd0 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 will sleep mult
11be0 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c iple times until
11bf0 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d at least "ms" m
11c00 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 illiseconds of s
11c10 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 leeping.** have
11c20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 7b 48 31 accumulated. {H1
11c30 32 33 34 33 7d 20 41 66 74 65 72 20 22 6d 73 22 2343} After "ms"
11c40 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 milliseconds of
11c50 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 sleeping,.** th
11c60 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e e handler return
11c70 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 s 0 which causes
11c80 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
11c90 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b ] to return.** [
11ca0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 SQLITE_BUSY] or
11cb0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c [SQLITE_IOERR_BL
11cc0 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61 OCKED]..**.** Ca
11cd0 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 lling this routi
11ce0 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d ne with an argum
11cf0 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 ent less than or
11d00 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a equal to zero.*
11d10 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 * turns off all
11d20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a busy handlers..*
11d30 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f *.** There can o
11d40 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 nly be a single
11d50 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 busy handler for
11d60 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a a particular.**
11d70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
11d80 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 ction] any any g
11d90 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 iven moment. If
11da0 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 another busy ha
11db0 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 ndler.** was def
11dc0 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 ined (using [sq
11dd0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c lite3_busy_handl
11de0 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 er()]) prior to
11df0 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 calling.** this
11e00 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 routine, that ot
11e10 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 her busy handler
11e20 20 69 73 20 63 6c 65 61 72 65 64 2e 0a 2a 2a 0a is cleared..**.
11e30 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
11e40 0a 2a 2a 20 5b 48 31 32 33 34 31 5d 20 5b 48 31 .** [H12341] [H1
11e50 32 33 34 33 5d 20 5b 48 31 32 33 34 34 5d 0a 2a 2343] [H12344].*
11e60 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
11e70 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 sqlite3_busy_ti
11e80 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 meout(sqlite3*,
11e90 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 int ms);../*.**
11ea0 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e CAPI3REF: Conven
11eb0 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 ience Routines F
11ec0 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 or Running Queri
11ed0 65 73 20 7b 48 31 32 33 37 30 7d 20 3c 53 31 30 es {H12370} <S10
11ee0 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 000>.**.** Defin
11ef0 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 ition: A <b>resu
11f00 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 lt table</b> is
11f10 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 memory data stru
11f20 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 cture created by
11f30 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
11f40 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e _get_table()] in
11f50 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 terface. A resu
11f60 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 lt table records
11f70 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 the.** complete
11f80 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 query results f
11f90 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 rom one or more
11fa0 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 queries..**.** T
11fb0 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 he table concept
11fc0 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 ually has a numb
11fd0 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 er of rows and c
11fe0 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 olumns. But.**
11ff0 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 these numbers ar
12000 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 e not part of th
12010 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 e result table i
12020 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a tself. These.**
12030 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 numbers are obt
12040 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 ained separately
12050 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 . Let N be the
12060 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a number of rows.*
12070 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e * and M be the n
12080 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
12090 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 ..**.** A result
120a0 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 table is an arr
120b0 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 ay of pointers t
120c0 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 o zero-terminate
120d0 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e d UTF-8 strings.
120e0 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e .** There are (N
120f0 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 +1)*M elements i
12100 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 n the array. Th
12110 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 e first M pointe
12120 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a rs point.** to z
12130 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 ero-terminated s
12140 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e trings that con
12150 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f tain the names o
12160 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a f the columns..*
12170 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 * The remaining
12180 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e entries all poin
12190 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c t to query resul
121a0 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 ts. NULL values
121b0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 result.** in NU
121c0 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c LL pointers. Al
121d0 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 l other values a
121e0 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d re in their UTF-
121f0 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 8 zero-terminate
12200 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 d.** string repr
12210 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 esentation as re
12220 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
12230 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
12240 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c ]..**.** A resul
12250 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f t table might co
12260 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 nsist of one or
12270 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f more memory allo
12280 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 cations..** It i
12290 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 s not safe to pa
122a0 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c ss a result tabl
122b0 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 e directly to [s
122c0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a qlite3_free()]..
122d0 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c ** A result tabl
122e0 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c e should be deal
122f0 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 located using [s
12300 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c qlite3_free_tabl
12310 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61 e()]..**.** As a
12320 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 n example of the
12330 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f result table fo
12340 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 rmat, suppose a
12350 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 query result.**
12360 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a is as follows:.*
12370 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
12380 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 ><pre>.**
12390 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 Name | A
123a0 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d ge.** ---
123b0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
123c0 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 ----.** A
123d0 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a lice | 43.
123e0 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 ** Bob
123f0 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 | 28.**
12400 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 Cindy
12410 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c | 21.** </pre><
12420 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
12430 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f ** There are two
12440 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 column (M==2) a
12450 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e nd three rows (N
12460 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a ==3). Thus the.
12470 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 ** result table
12480 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 has 8 entries.
12490 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 Suppose the resu
124a0 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 lt table is stor
124b0 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 ed.** in an arra
124c0 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 y names azResult
124d0 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 . Then azResult
124e0 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 holds this cont
124f0 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 ent:.**.** <bloc
12500 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 kquote><pre>.**
12510 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
12520 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b #91;0] = "Name";
12530 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 .** azRes
12540 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 ult[1] = "Ag
12550 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a e";.** az
12560 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 Result[2] =
12570 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 "Alice";.**
12580 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
12590 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 3] = "43";.**
125a0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
125b0 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 1;4] = "Bob";.**
125c0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
125d0 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a [5] = "28";.
125e0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
125f0 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e lt[6] = "Cin
12600 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 dy";.** a
12610 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d zResult[7] =
12620 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e "21";.** </pre>
12630 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a </blockquote>.**
12640 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
12650 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 get_table() func
12660 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f tion evaluates o
12670 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 ne or more.** se
12680 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 micolon-separate
12690 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 d SQL statements
126a0 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 in the zero-ter
126b0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a minated UTF-8.**
126c0 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 string of its 2
126d0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 nd parameter. I
126e0 74 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 t returns a resu
126f0 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a lt table to the.
12700 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e ** pointer given
12710 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 in its 3rd para
12720 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 meter..**.** Aft
12730 65 72 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 er the calling f
12740 75 6e 63 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 unction has fini
12750 73 68 65 64 20 75 73 69 6e 67 20 74 68 65 20 72 shed using the r
12760 65 73 75 6c 74 2c 20 69 74 20 73 68 6f 75 6c 64 esult, it should
12770 0a 2a 2a 20 70 61 73 73 20 74 68 65 20 70 6f 69 .** pass the poi
12780 6e 74 65 72 20 74 6f 20 74 68 65 20 72 65 73 75 nter to the resu
12790 6c 74 20 74 61 62 6c 65 20 74 6f 20 73 71 6c 69 lt table to sqli
127a0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 te3_free_table()
127b0 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 in order to.**
127c0 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f release the memo
127d0 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c ry that was mall
127e0 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f oced. Because o
127f0 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a f the way the.**
12800 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
12810 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 ()] happens with
12820 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 in sqlite3_get_t
12830 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c able(), the call
12840 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ing.** function
12850 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 must not try to
12860 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 call [sqlite3_fr
12870 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 ee()] directly.
12880 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 Only.** [sqlite
12890 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 3_free_table()]
128a0 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 is able to relea
128b0 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 se the memory pr
128c0 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c operly and safel
128d0 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c y..**.** The sql
128e0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
128f0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d interface is im
12900 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 plemented as a w
12910 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a rapper around.**
12920 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 [sqlite3_exec()
12930 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f ]. The sqlite3_
12940 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 get_table() rout
12950 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 ine does not hav
12960 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 e access.** to a
12970 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 ny internal data
12980 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 structures of S
12990 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 QLite. It uses
129a0 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a only the public.
129b0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 ** interface def
129c0 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 ined here. As a
129d0 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 consequence, er
129e0 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 rors that occur
129f0 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 in the.** wrappe
12a00 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 r layer outside
12a10 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 of the internal
12a20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
12a30 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a call are not.**
12a40 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 reflected in su
12a50 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 bsequent calls t
12a60 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f o [sqlite3_errco
12a70 64 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 de()] or [sqlite
12a80 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 3_errmsg()]..**.
12a90 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
12aa0 0a 2a 2a 20 5b 48 31 32 33 37 31 5d 20 5b 48 31 .** [H12371] [H1
12ab0 32 33 37 33 5d 20 5b 48 31 32 33 37 34 5d 20 5b 2373] [H12374] [
12ac0 48 31 32 33 37 36 5d 20 5b 48 31 32 33 37 39 5d H12376] [H12379]
12ad0 20 5b 48 31 32 33 38 32 5d 0a 2a 2f 0a 53 51 4c [H12382].*/.SQL
12ae0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
12af0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 te3_get_table(.
12b00 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
12b10 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 /* An ope
12b20 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 n database */.
12b30 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c const char *zSql
12b40 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 , /* SQL to
12b50 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a be evaluated */.
12b60 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 char ***pazRes
12b70 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c ult, /* Resul
12b80 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 ts of the query
12b90 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c */. int *pnRow,
12ba0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 /* Nu
12bb0 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 mber of result r
12bc0 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 ows written here
12bd0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c */. int *pnCol
12be0 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e umn, /* N
12bf0 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 umber of result
12c00 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 columns written
12c10 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a here */. char *
12c20 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 *pzErrmsg
12c30 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 /* Error msg wri
12c40 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a tten here */.);.
12c50 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
12c60 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 sqlite3_free_tab
12c70 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 le(char **result
12c80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
12c90 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 EF: Formatted St
12ca0 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 ring Printing Fu
12cb0 6e 63 74 69 6f 6e 73 20 7b 48 31 37 34 30 30 7d nctions {H17400}
12cc0 20 3c 53 37 30 30 30 30 3e 3c 53 32 30 30 30 30 <S70000><S20000
12cd0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f >.**.** These ro
12ce0 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d utines are work-
12cf0 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 alikes of the "p
12d00 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 rintf()" family
12d10 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 of functions.**
12d20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 from the standar
12d30 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a d C library..**.
12d40 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d ** The sqlite3_m
12d50 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c printf() and sql
12d60 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 ite3_vmprintf()
12d70 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 routines write t
12d80 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 heir.** results
12d90 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 into memory obta
12da0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 ined from [sqlit
12db0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a e3_malloc()]..**
12dc0 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 The strings ret
12dd0 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 urned by these t
12de0 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 wo routines shou
12df0 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 ld be.** release
12e00 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 d by [sqlite3_fr
12e10 65 65 28 29 5d 2e 20 20 42 6f 74 68 20 72 6f 75 ee()]. Both rou
12e20 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a tines return a.*
12e30 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 * NULL pointer i
12e40 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f f [sqlite3_mallo
12e50 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 c()] is unable t
12e60 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 o allocate enoug
12e70 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 h.** memory to h
12e80 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e old the resultin
12e90 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 g string..**.**
12ea0 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 In sqlite3_snpri
12eb0 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 ntf() routine is
12ec0 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 similar to "snp
12ed0 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a rintf()" from.**
12ee0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 the standard C
12ef0 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 library. The re
12f00 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 sult is written
12f10 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 into the.** buff
12f20 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 er supplied as t
12f30 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
12f40 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 ter whose size i
12f50 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 s given by.** th
12f60 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
12f70 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 r. Note that the
12f80 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a order of the.**
12f90 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d first two param
12fa0 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 eters is reverse
12fb0 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 d from snprintf(
12fc0 29 2e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a ). This is an.*
12fd0 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 * historical acc
12fe0 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f ident that canno
12ff0 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f t be fixed witho
13000 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 ut breaking.** b
13010 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 ackwards compati
13020 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65 20 61 6c bility. Note al
13030 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f so that sqlite3_
13040 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 snprintf().** re
13050 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
13060 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e to its buffer in
13070 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d stead of the num
13080 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 ber of.** charac
13090 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 ters actually wr
130a0 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 itten into the b
130b0 75 66 66 65 72 2e 20 20 57 65 20 61 64 6d 69 74 uffer. We admit
130c0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d that.** the num
130d0 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 ber of character
130e0 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 s written would
130f0 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c be a more useful
13100 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 return.** value
13110 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 but we cannot c
13120 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d hange the implem
13130 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 entation of sqli
13140 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a te3_snprintf().*
13150 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 * now without br
13160 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 eaking compatibi
13170 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c lity..**.** As l
13180 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 ong as the buffe
13190 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 r size is greate
131a0 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c r than zero, sql
131b0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a ite3_snprintf().
131c0 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 ** guarantees th
131d0 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 at the buffer is
131e0 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 always zero-ter
131f0 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20 66 69 minated. The fi
13200 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 rst.** parameter
13210 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 "n" is the tota
13220 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 l size of the bu
13230 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 ffer, including
13240 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 space for.** the
13250 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 zero terminator
13260 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 . So the longes
13270 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 t string that ca
13280 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a n be completely.
13290 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 ** written will
132a0 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 be n-1 character
132b0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 s..**.** These r
132c0 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c outines all impl
132d0 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 ement some addit
132e0 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 ional formatting
132f0 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 .** options that
13300 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 are useful for
13310 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c constructing SQL
13320 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 statements..**
13330 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c All of the usual
13340 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 printf() format
13350 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 ting options app
13360 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e ly. In addition
13370 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 , there.** is ar
13380 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e e "%q", "%Q", an
13390 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a d "%z" options..
133a0 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70 74 **.** The %q opt
133b0 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 ion works like %
133c0 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 s in that it sub
133d0 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d stitutes a null-
133e0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 terminated.** st
133f0 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 ring from the ar
13400 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 gument list. Bu
13410 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 t %q also double
13420 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 s every '\'' cha
13430 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 racter..** %q is
13440 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 designed for us
13450 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e e inside a strin
13460 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 79 20 64 g literal. By d
13470 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 oubling each '\'
13480 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 '.** character i
13490 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63 t escapes that c
134a0 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c haracter and all
134b0 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 ows it to be ins
134c0 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 erted into.** th
134d0 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 e string..**.**
134e0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 For example, ass
134f0 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 ume the string v
13500 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f ariable zText co
13510 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 ntains text as f
13520 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 ollows:.**.** <b
13530 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
13540 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 ** char *zText
13550 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20 = "It's a happy
13560 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e day!";.** </pre>
13570 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a </blockquote>.**
13580 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 .** One can use
13590 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 this text in an
135a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 SQL statement as
135b0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 follows:.**.**
135c0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
135d0 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c >.** char *zSQL
135e0 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e = sqlite3_mprin
135f0 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 tf("INSERT INTO
13600 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 table VALUES('%q
13610 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 ')", zText);.**
13620 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 sqlite3_exec(db
13630 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 , zSQL, 0, 0, 0)
13640 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 ;.** sqlite3_fr
13650 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 ee(zSQL);.** </p
13660 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
13670 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 .**.** Because t
13680 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 he %q format str
13690 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 ing is used, the
136a0 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 '\'' character
136b0 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 in zText.** is e
136c0 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 scaped and the S
136d0 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 QL generated is
136e0 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a as follows:.**.*
136f0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
13700 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 re>.** INSERT I
13710 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 NTO table1 VALUE
13720 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79 S('It''s a happy
13730 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 day!').** </pre
13740 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
13750 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 *.** This is cor
13760 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 rect. Had we us
13770 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 ed %s instead of
13780 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 %q, the generat
13790 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 ed SQL.** would
137a0 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 have looked like
137b0 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c this:.**.** <bl
137c0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
137d0 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 * INSERT INTO t
137e0 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 able1 VALUES('It
137f0 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 's a happy day!'
13800 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c );.** </pre></bl
13810 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
13820 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d This second exam
13830 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 ple is an SQL sy
13840 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 ntax error. As
13850 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 a general rule y
13860 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 ou should.** alw
13870 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 ays use %q inste
13880 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e ad of %s when in
13890 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 serting text int
138a0 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 o a string liter
138b0 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 51 al..**.** The %Q
138c0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 option works li
138d0 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20 ke %q except it
138e0 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 also adds single
138f0 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a quotes around.*
13900 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 * the outside of
13910 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e the total strin
13920 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 g. Additionally
13930 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 , if the paramet
13940 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 er in the.** arg
13950 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 ument list is a
13960 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 NULL pointer, %Q
13970 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65 substitutes the
13980 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 text "NULL" (wi
13990 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 thout.** single
139a0 71 75 6f 74 65 73 29 20 69 6e 20 70 6c 61 63 65 quotes) in place
139b0 20 6f 66 20 74 68 65 20 25 51 20 6f 70 74 69 6f of the %Q optio
139c0 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d n. So, for exam
139d0 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 ple, one could s
139e0 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b ay:.**.** <block
139f0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
13a00 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c char *zSQL = sql
13a10 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e ite3_mprintf("IN
13a20 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 SERT INTO table
13a30 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 VALUES(%Q)", zTe
13a40 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 xt);.** sqlite3
13a50 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 _exec(db, zSQL,
13a60 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 0, 0, 0);.** sq
13a70 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 lite3_free(zSQL)
13a80 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f ;.** </pre></blo
13a90 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 ckquote>.**.** T
13aa0 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 he code above wi
13ab0 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 ll render a corr
13ac0 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ect SQL statemen
13ad0 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a t in the zSQL.**
13ae0 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 variable even i
13af0 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 f the zText vari
13b00 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 able is a NULL p
13b10 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 ointer..**.** Th
13b20 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e e "%z" formattin
13b30 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 65 g option works e
13b40 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 25 73 22 xactly like "%s"
13b50 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 with the.** add
13b60 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 ition that after
13b70 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 the string has
13b80 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f been read and co
13b90 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 pied into.** the
13ba0 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 result, [sqlite
13bb0 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 3_free()] is cal
13bc0 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 led on the input
13bd0 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a 2a string. {END}.*
13be0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
13bf0 73 3a 0a 2a 2a 20 5b 48 31 37 34 30 33 5d 20 5b s:.** [H17403] [
13c00 48 31 37 34 30 36 5d 20 5b 48 31 37 34 30 37 5d H17406] [H17407]
13c10 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 .*/.SQLITE_API c
13c20 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 har *sqlite3_mpr
13c30 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a intf(const char*
13c40 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 ,...);.SQLITE_AP
13c50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f I char *sqlite3_
13c60 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 vmprintf(const c
13c70 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a har*, va_list);.
13c80 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 SQLITE_API char
13c90 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 *sqlite3_snprint
13ca0 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 f(int,char*,cons
13cb0 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a t char*, ...);..
13cc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
13cd0 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f Memory Allocatio
13ce0 6e 20 53 75 62 73 79 73 74 65 6d 20 7b 48 31 37 n Subsystem {H17
13cf0 33 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 300} <S20000>.**
13d00 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 .** The SQLite c
13d10 6f 72 65 20 20 75 73 65 73 20 74 68 65 73 65 20 ore uses these
13d20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 three routines f
13d30 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 or all of its ow
13d40 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 n.** internal me
13d50 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
13d60 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e needs. "Core" in
13d70 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 the previous se
13d80 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e ntence.** does n
13d90 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 ot include opera
13da0 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 ting-system spec
13db0 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 ific VFS impleme
13dc0 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a ntation. The.**
13dd0 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 Windows VFS use
13de0 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 s native malloc(
13df0 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 ) and free() for
13e00 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 some operations
13e10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
13e20 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 te3_malloc() rou
13e30 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 tine returns a p
13e40 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 ointer to a bloc
13e50 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 k.** of memory a
13e60 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 t least N bytes
13e70 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 in length, where
13e80 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 N is the parame
13e90 74 65 72 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 ter..** If sqlit
13ea0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 e3_malloc() is u
13eb0 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 nable to obtain
13ec0 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a sufficient free.
13ed0 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 ** memory, it re
13ee0 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 turns a NULL poi
13ef0 6e 74 65 72 2e 20 20 49 66 20 74 68 65 20 70 61 nter. If the pa
13f00 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 rameter N to.**
13f10 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
13f20 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 is zero or nega
13f30 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 tive then sqlite
13f40 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 3_malloc() retur
13f50 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 ns.** a NULL poi
13f60 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c nter..**.** Call
13f70 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 ing sqlite3_free
13f80 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 () with a pointe
13f90 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 r previously ret
13fa0 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 urned.** by sqli
13fb0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 te3_malloc() or
13fc0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
13fd0 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 ) releases that
13fe0 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 memory so.** tha
13ff0 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 t it might be re
14000 75 73 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74 used. The sqlit
14010 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e e3_free() routin
14020 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 e is.** a no-op
14030 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 if is called wit
14040 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 h a NULL pointer
14050 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c . Passing a NUL
14060 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 L pointer.** to
14070 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 sqlite3_free() i
14080 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 s harmless. Aft
14090 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 er being freed,
140a0 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 memory.** should
140b0 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 neither be read
140c0 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 nor written. E
140d0 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 ven reading prev
140e0 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 iously freed.**
140f0 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 memory might res
14100 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 ult in a segment
14110 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f ation fault or o
14120 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f ther severe erro
14130 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 r..** Memory cor
14140 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 ruption, a segme
14150 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f ntation fault, o
14160 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 r other severe e
14170 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 rror.** might re
14180 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f sult if sqlite3_
14190 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 free() is called
141a0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c with a non-NULL
141b0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a pointer that.**
141c0 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 was not obtaine
141d0 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d d from sqlite3_m
141e0 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 alloc() or sqlit
141f0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a e3_realloc()..**
14200 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
14210 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 realloc() interf
14220 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 ace attempts to
14230 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f resize a.** prio
14240 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 r memory allocat
14250 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 ion to be at lea
14260 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 st N bytes, wher
14270 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 e N is the.** se
14280 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 cond parameter.
14290 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f The memory allo
142a0 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 cation to be res
142b0 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73 ized is the firs
142c0 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 t.** parameter.
142d0 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61 If the first pa
142e0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
142f0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 e3_realloc().**
14300 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
14310 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 r then its behav
14320 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c ior is identical
14330 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 to calling.** s
14340 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 qlite3_malloc(N)
14350 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 where N is the
14360 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
14370 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c to sqlite3_real
14380 6c 6f 63 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65 loc()..** If the
14390 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
143a0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 r to sqlite3_rea
143b0 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f lloc() is zero o
143c0 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 r.** negative th
143d0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 en the behavior
143e0 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 is exactly the s
143f0 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a ame as calling.*
14400 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 * sqlite3_free(P
14410 29 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65 ) where P is the
14420 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
14430 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c to sqlite3_real
14440 6c 6f 63 28 29 2e 0a 2a 2a 20 73 71 6c 69 74 65 loc()..** sqlite
14450 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 3_realloc() retu
14460 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
14470 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
14480 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 tion.** of at le
14490 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 ast N bytes in s
144a0 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 ize or NULL if s
144b0 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 ufficient memory
144c0 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e is unavailable.
144d0 0a 2a 2a 20 49 66 20 4d 20 69 73 20 74 68 65 20 .** If M is the
144e0 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f size of the prio
144f0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 r allocation, th
14500 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 en min(N,M) byte
14510 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f s.** of the prio
14520 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 r allocation are
14530 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 copied into the
14540 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 beginning of bu
14550 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a ffer returned.**
14560 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c by sqlite3_real
14570 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 loc() and the pr
14580 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 ior allocation i
14590 73 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73 s freed..** If s
145a0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
145b0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 returns NULL, t
145c0 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c hen the prior al
145d0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e location.** is n
145e0 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 ot freed..**.**
145f0 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 The memory retur
14600 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d ned by sqlite3_m
14610 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 alloc() and sqli
14620 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a te3_realloc().**
14630 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e is always align
14640 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 ed to at least a
14650 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 n 8 byte boundar
14660 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 y. {END}.**.** T
14670 68 65 20 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 he default imple
14680 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 mentation of the
14690 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
146a0 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 75 73 65 on subsystem use
146b0 73 0a 2a 2a 20 74 68 65 20 6d 61 6c 6c 6f 63 28 s.** the malloc(
146c0 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 ), realloc() and
146d0 20 66 72 65 65 28 29 20 70 72 6f 76 69 64 65 64 free() provided
146e0 20 62 79 20 74 68 65 20 73 74 61 6e 64 61 72 64 by the standard
146f0 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 7b C library..** {
14700 48 31 37 33 38 32 7d 20 48 6f 77 65 76 65 72 2c H17382} However,
14710 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f if SQLite is co
14720 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a mpiled with the.
14730 2a 2a 20 53 51 4c 49 54 45 5f 4d 45 4d 4f 52 59 ** SQLITE_MEMORY
14740 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e _SIZE=<i>NNN</i>
14750 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 C preprocessor
14760 6d 61 63 72 6f 20 28 77 68 65 72 65 20 3c 69 3e macro (where <i>
14770 4e 4e 4e 3c 2f 69 3e 0a 2a 2a 20 69 73 20 61 6e NNN</i>.** is an
14780 20 69 6e 74 65 67 65 72 29 2c 20 74 68 65 6e 20 integer), then
14790 53 51 4c 69 74 65 20 63 72 65 61 74 65 20 61 20 SQLite create a
147a0 73 74 61 74 69 63 20 61 72 72 61 79 20 6f 66 20 static array of
147b0 61 74 20 6c 65 61 73 74 0a 2a 2a 20 3c 69 3e 4e at least.** <i>N
147c0 4e 4e 3c 2f 69 3e 20 62 79 74 65 73 20 69 6e 20 NN</i> bytes in
147d0 73 69 7a 65 20 61 6e 64 20 75 73 65 73 20 74 68 size and uses th
147e0 61 74 20 61 72 72 61 79 20 66 6f 72 20 61 6c 6c at array for all
147f0 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 0a of its dynamic.
14800 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ** memory alloca
14810 74 69 6f 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44 tion needs. {END
14820 7d 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 } Additional me
14830 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f mory allocator o
14840 70 74 69 6f 6e 73 0a 2a 2a 20 6d 61 79 20 62 65 ptions.** may be
14850 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 added in future
14860 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a releases..**.**
14870 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 In SQLite versi
14880 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 on 3.5.0 and 3.5
14890 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 .1, it was possi
148a0 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a ble to define.**
148b0 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 the SQLITE_OMIT
148c0 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 _MEMORY_ALLOCATI
148d0 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 ON which would c
148e0 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 ause the built-i
148f0 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 n.** implementat
14900 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 ion of these rou
14910 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 tines to be omit
14920 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 ted. That capab
14930 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c ility.** is no l
14940 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 onger provided.
14950 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d Only built-in m
14960 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 emory allocators
14970 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a can be used..**
14980 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20 .** The Windows
14990 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 OS interface lay
149a0 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 er calls.** the
149b0 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 system malloc()
149c0 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63 and free() direc
149d0 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 tly when convert
149e0 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 ing.** filenames
149f0 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 between the UTF
14a00 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 -8 encoding used
14a10 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e by SQLite.** an
14a20 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e d whatever filen
14a30 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 ame encoding is
14a40 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74 used by the part
14a50 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a icular Windows.*
14a60 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 * installation.
14a70 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 Memory allocati
14a80 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 65 on errors are de
14a90 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 tected, but.** t
14aa0 68 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 64 hey are reported
14ab0 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 back as [SQLITE
14ac0 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a _CANTOPEN] or.**
14ad0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 [SQLITE_IOERR]
14ae0 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c rather than [SQL
14af0 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a ITE_NOMEM]..**.*
14b00 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
14b10 2a 2a 20 5b 48 31 37 33 30 33 5d 20 5b 48 31 37 ** [H17303] [H17
14b20 33 30 34 5d 20 5b 48 31 37 33 30 35 5d 20 5b 48 304] [H17305] [H
14b30 31 37 33 30 36 5d 20 5b 48 31 37 33 31 30 5d 20 17306] [H17310]
14b40 5b 48 31 37 33 31 32 5d 20 5b 48 31 37 33 31 35 [H17312] [H17315
14b50 5d 20 5b 48 31 37 33 31 38 5d 0a 2a 2a 20 5b 48 ] [H17318].** [H
14b60 31 37 33 32 31 5d 20 5b 48 31 37 33 32 32 5d 20 17321] [H17322]
14b70 5b 48 31 37 33 32 33 5d 0a 2a 2a 0a 2a 2a 20 54 [H17323].**.** T
14b80 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d he pointer argum
14b90 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 ents to [sqlite3
14ba0 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 _free()] and [sq
14bb0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d lite3_realloc()]
14bc0 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 .** must be eith
14bd0 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 er NULL or else
14be0 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 pointers obtaine
14bf0 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a d from a prior.*
14c00 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 * invocation of
14c10 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
14c20 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 )] or [sqlite3_r
14c30 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 ealloc()] that h
14c40 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 ave.** not yet b
14c50 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a een released..**
14c60 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
14c70 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 ion must not rea
14c80 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 d or write any p
14c90 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 art of.** a bloc
14ca0 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 k of memory afte
14cb0 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 r it has been re
14cc0 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 leased using.**
14cd0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
14ce0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 or [sqlite3_rea
14cf0 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 lloc()]..*/.SQLI
14d00 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c TE_API void *sql
14d10 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 ite3_malloc(int)
14d20 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 ;.SQLITE_API voi
14d30 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c d *sqlite3_reall
14d40 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a oc(void*, int);.
14d50 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
14d60 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 sqlite3_free(voi
14d70 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 d*);../*.** CAPI
14d80 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 3REF: Memory All
14d90 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 ocator Statistic
14da0 73 20 7b 48 31 37 33 37 30 7d 20 3c 53 33 30 32 s {H17370} <S302
14db0 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 10>.**.** SQLite
14dc0 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 provides these
14dd0 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 two interfaces f
14de0 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 or reporting on
14df0 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 the status.** of
14e00 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 the [sqlite3_ma
14e10 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 lloc()], [sqlite
14e20 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 3_free()], and [
14e30 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
14e40 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 )].** routines,
14e50 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 which form the b
14e60 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 uilt-in memory a
14e70 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 llocation subsys
14e80 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 tem..**.** Requi
14e90 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 rements:.** [H17
14ea0 33 37 31 5d 20 5b 48 31 37 33 37 33 5d 20 5b 48 371] [H17373] [H
14eb0 31 37 33 37 34 5d 20 5b 48 31 37 33 37 35 5d 0a 17374] [H17375].
14ec0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 */.SQLITE_API sq
14ed0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 lite3_int64 sqli
14ee0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 te3_memory_used(
14ef0 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 void);.SQLITE_AP
14f00 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 I sqlite3_int64
14f10 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 sqlite3_memory_h
14f20 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 ighwater(int res
14f30 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 etFlag);../*.**
14f40 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f CAPI3REF: Pseudo
14f50 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 -Random Number G
14f60 65 6e 65 72 61 74 6f 72 20 7b 48 31 37 33 39 30 enerator {H17390
14f70 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a } <S20000>.**.**
14f80 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 SQLite contains
14f90 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 a high-quality
14fa0 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 pseudo-random nu
14fb0 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 mber generator (
14fc0 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a PRNG) used to.**
14fd0 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b select random [
14fe0 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 ROWID | ROWIDs]
14ff0 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e when inserting n
15000 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 ew records into
15010 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 a table that.**
15020 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 already uses the
15030 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c largest possibl
15040 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 e [ROWID]. The
15050 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 PRNG is also use
15060 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 d for.** the bui
15070 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 ld-in random() a
15080 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 nd randomblob()
15090 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 SQL functions.
150a0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 This interface a
150b0 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 llows.** applica
150c0 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 tions to access
150d0 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f the same PRNG fo
150e0 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 r other purposes
150f0 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 ..**.** A call t
15100 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 o this routine s
15110 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 tores N bytes of
15120 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f randomness into
15130 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a buffer P..**.**
15140 20 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 The first time
15150 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 this routine is
15160 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 invoked (either
15170 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 internally or by
15180 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 .** the applicat
15190 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 ion) the PRNG is
151a0 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 seeded using ra
151b0 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 ndomness obtaine
151c0 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 d.** from the xR
151d0 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 andomness method
151e0 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 of the default
151f0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 [sqlite3_vfs] ob
15200 6a 65 63 74 2e 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 ject..** On all
15210 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 subsequent invoc
15220 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 ations, the pseu
15230 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 do-randomness is
15240 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e generated.** in
15250 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 ternally and wit
15260 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f hout recourse to
15270 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 the [sqlite3_vf
15280 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a s] xRandomness.*
15290 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 * method..**.**
152a0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
152b0 20 5b 48 31 37 33 39 32 5d 0a 2a 2f 0a 53 51 4c [H17392].*/.SQL
152c0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c ITE_API void sql
152d0 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 ite3_randomness(
152e0 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b int N, void *P);
152f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
15300 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 : Compile-Time A
15310 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c uthorization Cal
15320 6c 62 61 63 6b 73 20 7b 48 31 32 35 30 30 7d 20 lbacks {H12500}
15330 3c 53 37 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S70100>.**.** T
15340 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 his routine regi
15350 73 74 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a sters a authoriz
15360 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 er callback with
15370 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a a particular.**
15380 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
15390 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 ction], supplied
153a0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
153b0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 61 gument..** The a
153c0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
153d0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 ck is invoked as
153e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
153f0 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c are being compil
15400 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 ed.** by [sqlite
15410 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 3_prepare()] or
15420 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 its variants [sq
15430 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
15440 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
15450 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e _prepare16()] an
15460 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 d [sqlite3_prepa
15470 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 41 74 20 re16_v2()]. At
15480 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 various.** point
15490 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d s during the com
154a0 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 pilation process
154b0 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 , as logic is be
154c0 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 ing created.** t
154d0 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 o perform variou
154e0 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 s actions, the a
154f0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
15500 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f ck is invoked to
15510 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 .** see if those
15520 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c actions are all
15530 6f 77 65 64 2e 20 20 54 68 65 20 61 75 74 68 6f owed. The autho
15540 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 rizer callback s
15550 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 hould.** return
15560 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 [SQLITE_OK] to a
15570 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c llow the action,
15580 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d [SQLITE_IGNORE]
15590 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 to disallow the
155a0 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 .** specific act
155b0 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 ion but allow th
155c0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
155d0 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 to continue to b
155e0 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f e.** compiled, o
155f0 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 r [SQLITE_DENY]
15600 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 to cause the ent
15610 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ire SQL statemen
15620 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 t to be.** rejec
15630 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f ted with an erro
15640 72 2e 20 20 49 66 20 74 68 65 20 61 75 74 68 6f r. If the autho
15650 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 rizer callback r
15660 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 eturns.** any va
15670 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b lue other than [
15680 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 SQLITE_IGNORE],
15690 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 [SQLITE_OK], or
156a0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a [SQLITE_DENY].**
156b0 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 then the [sqlit
156c0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
156d0 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 or equivalent c
156e0 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 all that trigger
156f0 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 ed.** the author
15700 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 izer will fail w
15710 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 ith an error mes
15720 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e sage..**.** When
15730 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 the callback re
15740 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b turns [SQLITE_OK
15750 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 ], that means th
15760 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 e operation.** r
15770 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 equested is ok.
15780 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 When the callba
15790 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 ck returns [SQLI
157a0 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a TE_DENY], the.**
157b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
157c0 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 e_v2()] or equiv
157d0 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 alent call that
157e0 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a triggered the.**
157f0 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c authorizer will
15800 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 fail with an er
15810 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c ror message expl
15820 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 aining that.** a
15830 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e ccess is denied.
15840 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 .**.** The firs
15850 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 t parameter to t
15860 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
15870 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 llback is a copy
15880 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a of the third.**
15890 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
158a0 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 e sqlite3_set_au
158b0 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 thorizer() inter
158c0 66 61 63 65 2e 20 54 68 65 20 73 65 63 6f 6e 64 face. The second
158d0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f parameter.** to
158e0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 the callback is
158f0 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c an integer [SQL
15900 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f ITE_COPY | actio
15910 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 n code] that spe
15920 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 cifies.** the pa
15930 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 rticular action
15940 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 to be authorized
15950 2e 20 54 68 65 20 74 68 69 72 64 20 74 68 72 6f . The third thro
15960 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 ugh sixth parame
15970 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 ters.** to the c
15980 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f allback are zero
15990 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 -terminated stri
159a0 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e ngs that contain
159b0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 additional.** d
159c0 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 etails about the
159d0 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 action to be au
159e0 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 thorized..**.**
159f0 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f If the action co
15a00 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 de is [SQLITE_RE
15a10 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 AD].** and the c
15a20 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
15a30 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 [SQLITE_IGNORE]
15a40 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 then the.** [pre
15a50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
15a60 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f statement is co
15a70 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 nstructed to sub
15a80 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c stitute.** a NUL
15a90 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 L value in place
15aa0 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f of the table co
15ab0 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 lumn that would
15ac0 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 have.** been rea
15ad0 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d d if [SQLITE_OK]
15ae0 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e had been return
15af0 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 ed. The [SQLITE
15b00 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 _IGNORE].** retu
15b10 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 rn can be used t
15b20 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 o deny an untrus
15b30 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 ted user access
15b40 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a to individual.**
15b50 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 columns of a ta
15b60 62 6c 65 2e 0a 2a 2a 20 49 66 20 74 68 65 20 61 ble..** If the a
15b70 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 ction code is [S
15b80 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e QLITE_DELETE] an
15b90 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 d the callback r
15ba0 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 eturns.** [SQLIT
15bb0 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 E_IGNORE] then t
15bc0 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 he [DELETE] oper
15bd0 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 ation proceeds b
15be0 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 ut the.** [trunc
15bf0 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e ate optimization
15c00 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e ] is disabled an
15c10 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 d all rows are d
15c20 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 eleted individua
15c30 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 lly..**.** An au
15c40 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 thorizer is used
15c50 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 when [sqlite3_p
15c60 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 repare | prepari
15c70 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 ng].** SQL state
15c80 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e ments from an un
15c90 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 trusted source,
15ca0 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 to ensure that t
15cb0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
15cc0 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 s.** do not try
15cd0 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74 to access data t
15ce0 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f hey are not allo
15cf0 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 wed to see, or t
15d00 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a hat they do not.
15d10 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 ** try to execut
15d20 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 e malicious stat
15d30 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 ements that dama
15d40 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e ge the database.
15d50 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 For.** example
15d60 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e , an application
15d70 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 may allow a use
15d80 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 r to enter arbit
15d90 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 rary.** SQL quer
15da0 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 ies for evaluati
15db0 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 on by a database
15dc0 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 . But the appli
15dd0 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e cation does.** n
15de0 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 ot want the user
15df0 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d to be able to m
15e00 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 ake arbitrary ch
15e10 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 anges to the.**
15e20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 database. An au
15e30 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 thorizer could t
15e40 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c hen be put in pl
15e50 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a ace while the.**
15e60 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 user-entered SQ
15e70 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 L is being [sqli
15e80 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 te3_prepare | pr
15e90 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 epared] that.**
15ea0 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 disallows everyt
15eb0 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c hing except [SEL
15ec0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e ECT] statements.
15ed0 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 .**.** Applicati
15ee0 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f ons that need to
15ef0 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f process SQL fro
15f00 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 m untrusted sour
15f10 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 ces.** might als
15f20 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 o consider lower
15f30 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d ing resource lim
15f40 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 its using [sqlit
15f50 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 e3_limit()].** a
15f60 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 nd limiting data
15f70 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 base size using
15f80 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f the [max_page_co
15f90 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a unt] [PRAGMA].**
15fa0 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 in addition to
15fb0 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 using an authori
15fc0 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 zer..**.** Only
15fd0 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 a single authori
15fe0 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c zer can be in pl
15ff0 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 ace on a databas
16000 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
16010 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 at a time. Each
16020 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
16030 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 _set_authorizer
16040 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a overrides the.**
16050 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 20 previous call.
16060 20 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 Disable the aut
16070 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 horizer by insta
16080 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c lling a NULL cal
16090 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 lback..** The au
160a0 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 thorizer is disa
160b0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e bled by default.
160c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f .**.** The autho
160d0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d rizer callback m
160e0 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 ust not do anyth
160f0 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f ing that will mo
16100 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 dify.** the data
16110 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
16120 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 that invoked the
16130 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
16140 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 back..** Note th
16150 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 at [sqlite3_prep
16160 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 are_v2()] and [s
16170 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 qlite3_step()] b
16180 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 oth modify their
16190 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
161a0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 nections for the
161b0 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 meaning of "mod
161c0 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 ify" in this par
161d0 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 57 68 agraph..**.** Wh
161e0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 en [sqlite3_prep
161f0 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 are_v2()] is use
16200 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 d to prepare a s
16210 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a tatement, the.**
16220 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 statement might
16230 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 be re-prepared
16240 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f during [sqlite3_
16250 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 step()] due to a
16260 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e .** schema chan
16270 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 ge. Hence, the
16280 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 application shou
16290 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 ld ensure that t
162a0 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 he.** correct au
162b0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
162c0 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 k remains in pla
162d0 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 ce during the [s
162e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a qlite3_step()]..
162f0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 **.** Note that
16300 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
16310 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
16320 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a ed only during.*
16330 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
16340 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 re()] or its var
16350 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a iants. Authoriz
16360 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 ation is not.**
16370 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 performed during
16380 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 statement evalu
16390 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 ation in [sqlite
163a0 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 3_step()], unles
163b0 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 s.** as stated i
163c0 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 n the previous p
163d0 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 aragraph, sqlite
163e0 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 3_step() invokes
163f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 .** sqlite3_prep
16400 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 are_v2() to repr
16410 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e epare a statemen
16420 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 t after a schema
16430 20 63 68 61 6e 67 65 2e 0a 2a 2a 0a 2a 2a 20 52 change..**.** R
16440 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
16450 5b 48 31 32 35 30 31 5d 20 5b 48 31 32 35 30 32 [H12501] [H12502
16460 5d 20 5b 48 31 32 35 30 33 5d 20 5b 48 31 32 35 ] [H12503] [H125
16470 30 34 5d 20 5b 48 31 32 35 30 35 5d 20 5b 48 31 04] [H12505] [H1
16480 32 35 30 36 5d 20 5b 48 31 32 35 30 37 5d 20 5b 2506] [H12507] [
16490 48 31 32 35 31 30 5d 0a 2a 2a 20 5b 48 31 32 35 H12510].** [H125
164a0 31 31 5d 20 5b 48 31 32 35 31 32 5d 20 5b 48 31 11] [H12512] [H1
164b0 32 35 32 30 5d 20 5b 48 31 32 35 32 31 5d 20 5b 2520] [H12521] [
164c0 48 31 32 35 32 32 5d 0a 2a 2f 0a 53 51 4c 49 54 H12522].*/.SQLIT
164d0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
164e0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
164f0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 (. sqlite3*,.
16500 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 int (*xAuth)(voi
16510 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 d*,int,const cha
16520 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 r*,const char*,c
16530 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 onst char*,const
16540 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 char*),. void
16550 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f *pUserData.);../
16560 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 *.** CAPI3REF: A
16570 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e uthorizer Return
16580 20 43 6f 64 65 73 20 7b 48 31 32 35 39 30 7d 20 Codes {H12590}
16590 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <H12500>.**.** T
165a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f he [sqlite3_set_
165b0 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 authorizer | aut
165c0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
165d0 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a function] must.
165e0 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 ** return either
165f0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 [SQLITE_OK] or
16600 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f one of these two
16610 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 constants in or
16620 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c der.** to signal
16630 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 SQLite whether
16640 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f or not the actio
16650 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 n is permitted.
16660 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c See the.** [sql
16670 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
16680 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 zer | authorizer
16690 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 documentation]
166a0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a for additional.*
166b0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a * information..*
166c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
166d0 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 _DENY 1 /* A
166e0 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 bort the SQL sta
166f0 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 tement with an e
16700 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 rror */.#define
16710 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 SQLITE_IGNORE 2
16720 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 /* Don't allow
16730 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e access, but don
16740 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 't generate an e
16750 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 rror */../*.** C
16760 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 API3REF: Authori
16770 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 zer Action Codes
16780 20 7b 48 31 32 35 35 30 7d 20 3c 48 31 32 35 30 {H12550} <H1250
16790 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 0>.**.** The [sq
167a0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
167b0 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 izer()] interfac
167c0 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 e registers a ca
167d0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a llback function.
167e0 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b ** that is invok
167f0 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 ed to authorize
16800 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 certain SQL stat
16810 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 ement actions.
16820 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 The.** second pa
16830 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 rameter to the c
16840 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e allback is an in
16850 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 teger code that
16860 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 specifies.** wha
16870 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e t action is bein
16880 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 g authorized. T
16890 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 hese are the int
168a0 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 eger action code
168b0 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 s that.** the au
168c0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
168d0 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e k may be passed.
168e0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 .**.** These act
168f0 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 ion code values
16900 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e signify what kin
16910 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 d of operation i
16920 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f s to be.** autho
16930 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 rized. The 3rd
16940 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 and 4th paramete
16950 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 rs to the author
16960 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 ization.** callb
16970 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c ack function wil
16980 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 l be parameters
16990 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e or NULL dependin
169a0 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 g on which of th
169b0 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 ese.** codes is
169c0 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f used as the seco
169d0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 nd parameter. T
169e0 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 he 5th parameter
169f0 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f to the.** autho
16a00 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 rizer callback i
16a10 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
16a20 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 e database ("mai
16a30 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 n", "temp",.** e
16a40 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 tc.) if applicab
16a50 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70 61 72 le. The 6th par
16a60 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 ameter to the au
16a70 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
16a80 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 k.** is the name
16a90 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f of the inner-mo
16aa0 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 st trigger or vi
16ab0 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f ew that is respo
16ac0 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 nsible for.** th
16ad0 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 e access attempt
16ae0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 or NULL if this
16af0 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 access attempt
16b00 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d is directly from
16b10 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 .** top-level SQ
16b20 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 L code..**.** Re
16b30 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
16b40 48 31 32 35 35 31 5d 20 5b 48 31 32 35 35 32 5d H12551] [H12552]
16b50 20 5b 48 31 32 35 35 33 5d 20 5b 48 31 32 35 35 [H12553] [H1255
16b60 34 5d 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 4].*/./*********
16b70 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
16b80 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
16b90 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a ** 3rd *********
16ba0 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a *** 4th ********
16bb0 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ***/.#define SQL
16bc0 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 ITE_CREATE_INDEX
16bd0 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 1 /*
16be0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 Index Name
16bf0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
16c00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
16c10 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 TE_CREATE_TABLE
16c20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 2 /*
16c30 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
16c40 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
16c50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
16c60 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e E_CREATE_TEMP_IN
16c70 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 DEX 3 /* I
16c80 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 ndex Name T
16c90 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
16ca0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
16cb0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 _CREATE_TEMP_TAB
16cc0 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 LE 4 /* Ta
16cd0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
16ce0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
16cf0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
16d00 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 CREATE_TEMP_TRIG
16d10 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 GER 5 /* Tri
16d20 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 gger Name Tab
16d30 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
16d40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
16d50 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 REATE_TEMP_VIEW
16d60 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 6 /* View
16d70 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c Name NULL
16d80 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
16d90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
16da0 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 EATE_TRIGGER
16db0 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 7 /* Trigg
16dc0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 er Name Table
16dd0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
16de0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
16df0 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 ATE_VIEW
16e00 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 8 /* View N
16e10 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 ame NULL
16e20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
16e30 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 fine SQLITE_DELE
16e40 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TE
16e50 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 9 /* Table N
16e60 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
16e70 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
16e80 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
16e90 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 INDEX
16ea0 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 10 /* Index Na
16eb0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 me Table Na
16ec0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
16ed0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
16ee0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 ABLE 1
16ef0 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 1 /* Table Nam
16f00 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
16f10 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
16f20 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 e SQLITE_DROP_TE
16f30 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 MP_INDEX 12
16f40 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 /* Index Name
16f50 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 Table Name
16f60 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
16f70 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d SQLITE_DROP_TEM
16f80 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 P_TABLE 13
16f90 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
16fa0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
16fb0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
16fc0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 SQLITE_DROP_TEMP
16fd0 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20 _TRIGGER 14
16fe0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 /* Trigger Name
16ff0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
17000 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
17010 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f QLITE_DROP_TEMP_
17020 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20 VIEW 15
17030 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 /* View Name
17040 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
17050 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
17060 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 LITE_DROP_TRIGGE
17070 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f R 16 /
17080 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 * Trigger Name
17090 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
170a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
170b0 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 ITE_DROP_VIEW
170c0 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 17 /*
170d0 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 View Name
170e0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
170f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
17100 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 TE_INSERT
17110 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 18 /*
17120 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
17130 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
17140 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
17150 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 E_PRAGMA
17160 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 19 /* P
17170 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 ragma Name 1
17180 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a st arg or NULL *
17190 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
171a0 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 _READ
171b0 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 20 /* Ta
171c0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f ble Name Co
171d0 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f lumn Name */
171e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
171f0 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 SELECT
17200 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 21 /* NUL
17210 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c L NUL
17220 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
17230 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
17240 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 RANSACTION
17250 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 22 /* Oper
17260 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c ation NULL
17270 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
17280 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 define SQLITE_UP
17290 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 DATE
172a0 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 23 /* Table
172b0 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d Name Colum
172c0 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 n Name */.#d
172d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 efine SQLITE_ATT
172e0 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 ACH
172f0 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 24 /* Filena
17300 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 me NULL
17310 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
17320 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 fine SQLITE_DETA
17330 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 CH
17340 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 25 /* Databas
17350 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 e Name NULL
17360 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
17370 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 ine SQLITE_ALTER
17380 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 _TABLE
17390 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 26 /* Database
173a0 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 Name Table Na
173b0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
173c0 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 ne SQLITE_REINDE
173d0 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 X 2
173e0 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 7 /* Index Nam
173f0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
17400 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
17410 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 e SQLITE_ANALYZE
17420 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38 28
17430 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
17440 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
17450 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
17460 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 SQLITE_CREATE_V
17470 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 TABLE 29
17480 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
17490 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 Module Name
174a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
174b0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 SQLITE_DROP_VTAB
174c0 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20 LE 30
174d0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
174e0 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 Module Name
174f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
17500 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 QLITE_FUNCTION
17510 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20 31
17520 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 /* NULL
17530 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 Function Name
17540 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
17550 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 LITE_SAVEPOINT
17560 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 32 /
17570 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 * Operation
17580 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 Savepoint Name
17590 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
175a0 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 ITE_COPY
175b0 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 0 /*
175c0 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 No longer used
175d0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
175e0 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 EF: Tracing And
175f0 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 Profiling Functi
17600 6f 6e 73 20 7b 48 31 32 32 38 30 7d 20 3c 53 36 ons {H12280} <S6
17610 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 0400>.** EXPERIM
17620 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ENTAL.**.** Thes
17630 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 e routines regis
17640 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e ter callback fun
17650 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 ctions that can
17660 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 be used for.** t
17670 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 racing and profi
17680 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 ling the executi
17690 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d on of SQL statem
176a0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ents..**.** The
176b0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
176c0 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 n registered by
176d0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 sqlite3_trace()
176e0 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a is invoked at.**
176f0 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 various times w
17700 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 hen an SQL state
17710 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 ment is being ru
17720 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 n by [sqlite3_st
17730 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 63 61 ep()]..** The ca
17740 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 llback returns a
17750 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 UTF-8 rendering
17760 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 of the SQL stat
17770 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a 20 61 73 ement text.** as
17780 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 the statement f
17790 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 irst begins exec
177a0 75 74 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e uting. Addition
177b0 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 6f 63 63 al callbacks occ
177c0 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 ur.** as each tr
177d0 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 iggered subprogr
177e0 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 am is entered.
177f0 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f The callbacks fo
17800 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f r triggers.** co
17810 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 ntain a UTF-8 SQ
17820 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 L comment that i
17830 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 dentifies the tr
17840 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 igger..**.** The
17850 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
17860 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 on registered by
17870 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 sqlite3_profile
17880 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a () is invoked.**
17890 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 as each SQL sta
178a0 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e tement finishes.
178b0 20 20 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 The profile ca
178c0 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a llback contains.
178d0 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 ** the original
178e0 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 statement text a
178f0 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f nd an estimate o
17900 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d f wall-clock tim
17910 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 e.** of how long
17920 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 that statement
17930 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a took to run..**.
17940 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
17950 0a 2a 2a 20 5b 48 31 32 32 38 31 5d 20 5b 48 31 .** [H12281] [H1
17960 32 32 38 32 5d 20 5b 48 31 32 32 38 33 5d 20 5b 2282] [H12283] [
17970 48 31 32 32 38 34 5d 20 5b 48 31 32 32 38 35 5d H12284] [H12285]
17980 20 5b 48 31 32 32 38 37 5d 20 5b 48 31 32 32 38 [H12287] [H1228
17990 38 5d 20 5b 48 31 32 32 38 39 5d 0a 2a 2a 20 5b 8] [H12289].** [
179a0 48 31 32 32 39 30 5d 0a 2a 2f 0a 53 51 4c 49 54 H12290].*/.SQLIT
179b0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 E_API SQLITE_EXP
179c0 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a ERIMENTAL void *
179d0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 sqlite3_trace(sq
179e0 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 lite3*, void(*xT
179f0 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 race)(void*,cons
17a00 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 t char*), void*)
17a10 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c ;.SQLITE_API SQL
17a20 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c ITE_EXPERIMENTAL
17a30 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 void *sqlite3_p
17a40 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c rofile(sqlite3*,
17a50 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 . void(*xProfi
17a60 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 le)(void*,const
17a70 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 char*,sqlite3_ui
17a80 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a nt64), void*);..
17a90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
17aa0 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 Query Progress C
17ab0 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 31 30 allbacks {H12910
17ac0 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a } <S60400>.**.**
17ad0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f This routine co
17ae0 6e 66 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62 nfigures a callb
17af0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 ack function - t
17b00 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20 63 he.** progress c
17b10 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74 20 69 allback - that i
17b20 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 s invoked period
17b30 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f ically during lo
17b40 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61 ng.** running ca
17b50 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
17b60 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 exec()], [sqlite
17b70 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a 3_step()] and.**
17b80 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 [sqlite3_get_ta
17b90 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d ble()]. An exam
17ba0 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 ple use for this
17bb0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 .** interface is
17bc0 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 to keep a GUI u
17bd0 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 pdated during a
17be0 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a large query..**.
17bf0 2a 2a 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 ** If the progre
17c00 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 ss callback retu
17c10 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 rns non-zero, th
17c20 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a e operation is.*
17c30 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 * interrupted.
17c40 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e This feature can
17c50 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c be used to impl
17c60 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 ement a.** "Canc
17c70 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 el" button on a
17c80 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 GUI progress dia
17c90 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 log box..**.** T
17ca0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 he progress hand
17cb0 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 ler must not do
17cc0 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 anything that wi
17cd0 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 ll modify.** the
17ce0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
17cf0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 tion that invoke
17d00 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 d the progress h
17d10 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 andler..** Note
17d20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 that [sqlite3_pr
17d30 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 epare_v2()] and
17d40 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
17d50 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 both modify the
17d60 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 ir.** database c
17d70 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 onnections for t
17d80 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d he meaning of "m
17d90 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 odify" in this p
17da0 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 aragraph..**.**
17db0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
17dc0 20 5b 48 31 32 39 31 31 5d 20 5b 48 31 32 39 31 [H12911] [H1291
17dd0 32 5d 20 5b 48 31 32 39 31 33 5d 20 5b 48 31 32 2] [H12913] [H12
17de0 39 31 34 5d 20 5b 48 31 32 39 31 35 5d 20 5b 48 914] [H12915] [H
17df0 31 32 39 31 36 5d 20 5b 48 31 32 39 31 37 5d 20 12916] [H12917]
17e00 5b 48 31 32 39 31 38 5d 0a 2a 2a 0a 2a 2f 0a 53 [H12918].**.*/.S
17e10 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
17e20 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f qlite3_progress_
17e30 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a handler(sqlite3*
17e40 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f , int, int(*)(vo
17e50 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f id*), void*);../
17e60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
17e70 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 pening A New Dat
17e80 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e abase Connection
17e90 20 7b 48 31 32 37 30 30 7d 20 3c 53 34 30 32 30 {H12700} <S4020
17ea0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 0>.**.** These r
17eb0 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 outines open an
17ec0 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 SQLite database
17ed0 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20 file whose name
17ee0 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a is given by the.
17ef0 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 ** filename argu
17f00 6d 65 6e 74 2e 20 54 68 65 20 66 69 6c 65 6e 61 ment. The filena
17f10 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 me argument is i
17f20 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 nterpreted as UT
17f30 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 F-8 for.** sqlit
17f40 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 e3_open() and sq
17f50 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
17f60 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e and as UTF-16 in
17f70 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 the native byte
17f80 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 .** order for sq
17f90 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 lite3_open16().
17fa0 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e A [database conn
17fb0 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 ection] handle i
17fc0 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 s usually.** ret
17fd0 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 urned in *ppDb,
17fe0 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 even if an error
17ff0 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e occurs. The on
18000 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 ly exception is
18010 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 that.** if SQLit
18020 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 e is unable to a
18030 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 llocate memory t
18040 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 o hold the [sqli
18050 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 te3] object,.**
18060 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 a NULL will be w
18070 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 ritten into *ppD
18080 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 b instead of a p
18090 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 ointer to the [s
180a0 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 qlite3].** objec
180b0 74 2e 20 49 66 20 74 68 65 20 64 61 74 61 62 61 t. If the databa
180c0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e se is opened (an
180d0 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 d/or created) su
180e0 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e ccessfully, then
180f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 .** [SQLITE_OK]
18100 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 is returned. Ot
18110 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f herwise an [erro
18120 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 r code] is retur
18130 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 ned. The.** [sq
18140 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 lite3_errmsg()]
18150 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d or [sqlite3_errm
18160 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 sg16()] routines
18170 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
18180 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 obtain.** an Eng
18190 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 lish language de
181a0 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 scription of the
181b0 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 error..**.** Th
181c0 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 e default encodi
181d0 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 ng for the datab
181e0 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d ase will be UTF-
181f0 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 8 if.** sqlite3_
18200 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 open() or sqlite
18210 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 3_open_v2() is c
18220 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 alled and.** UTF
18230 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 -16 in the nativ
18240 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 e byte order if
18250 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
18260 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 is used..**.**
18270 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 Whether or not a
18280 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 n error occurs w
18290 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 hen it is opened
182a0 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 , resources.** a
182b0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
182c0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
182d0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 nection] handle
182e0 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 should be releas
182f0 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 ed by.** passing
18300 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f it to [sqlite3_
18310 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 close()] when it
18320 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 is no longer re
18330 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 quired..**.** Th
18340 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 e sqlite3_open_v
18350 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 2() interface wo
18360 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 rks like sqlite3
18370 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 _open().** excep
18380 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 t that it accept
18390 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c s two additional
183a0 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 parameters for
183b0 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 additional contr
183c0 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e ol.** over the n
183d0 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ew database conn
183e0 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61 ection. The fla
183f0 67 73 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e gs parameter can
18400 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 take one of.**
18410 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 the following th
18420 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 ree values, opti
18430 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 onally combined
18440 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 with the .** [SQ
18450 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 LITE_OPEN_NOMUTE
18460 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e X], [SQLITE_OPEN
18470 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 _FULLMUTEX], [SQ
18480 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 LITE_OPEN_SHARED
18490 43 41 43 48 45 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f CACHE],.** and/o
184a0 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 r [SQLITE_OPEN_P
184b0 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 RIVATECACHE] fla
184c0 67 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a gs:.**.** <dl>.*
184d0 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 * <dt>[SQLITE_OP
184e0 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 EN_READONLY]</dt
184f0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 >.** <dd>The dat
18500 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 abase is opened
18510 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 in read-only mod
18520 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62 e. If the datab
18530 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 ase does not.**
18540 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 already exist, a
18550 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 n error is retur
18560 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ned.</dd>.**.**
18570 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e <dt>[SQLITE_OPEN
18580 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e _READWRITE]</dt>
18590 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 .** <dd>The data
185a0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 base is opened f
185b0 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 or reading and w
185c0 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 riting if possib
185d0 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a le, or reading.*
185e0 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 * only if the fi
185f0 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 le is write prot
18600 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 ected by the ope
18610 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 rating system.
18620 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 In either.** cas
18630 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d e the database m
18640 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 ust already exis
18650 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 t, otherwise an
18660 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 error is returne
18670 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 d.</dd>.**.** <d
18680 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 t>[SQLITE_OPEN_R
18690 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c EADWRITE] | [SQL
186a0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d ITE_OPEN_CREATE]
186b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
186c0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
186d0 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 ned for reading
186e0 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 and writing, and
186f0 20 69 73 20 63 72 65 61 74 65 73 20 69 74 20 69 is creates it i
18700 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 f.** it does not
18710 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 already exist.
18720 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 This is the beha
18730 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 vior that is alw
18740 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 ays used for.**
18750 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 sqlite3_open() a
18760 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 nd sqlite3_open1
18770 36 28 29 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6().</dd>.** </d
18780 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 l>.**.** If the
18790 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 3rd parameter to
187a0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
187b0 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 () is not one of
187c0 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 the.** combinat
187d0 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 ions shown above
187e0 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 or one of the c
187f0 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 ombinations show
18800 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e 65 64 n above combined
18810 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 .** with the [SQ
18820 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 LITE_OPEN_NOMUTE
18830 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e X], [SQLITE_OPEN
18840 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 0a 2a 2a 20 _FULLMUTEX],.**
18850 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 [SQLITE_OPEN_SHA
18860 52 45 44 43 41 43 48 45 5d 20 61 6e 64 2f 6f 72 REDCACHE] and/or
18870 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 [SQLITE_OPEN_SH
18880 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 73 AREDCACHE] flags
18890 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 ,.** then the be
188a0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 havior is undefi
188b0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ned..**.** If th
188c0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e e [SQLITE_OPEN_N
188d0 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 OMUTEX] flag is
188e0 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 set, then the da
188f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
18900 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 n.** opens in th
18910 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b e multi-thread [
18920 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
18930 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 as long as the s
18940 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 ingle-thread.**
18950 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 mode has not bee
18960 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 n set at compile
18970 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 -time or start-t
18980 69 6d 65 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 ime. If the.**
18990 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c [SQLITE_OPEN_FUL
189a0 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 LMUTEX] flag is
189b0 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 set then the dat
189c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
189d0 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 opens.** in the
189e0 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 serialized [thr
189f0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c eading mode] unl
18a00 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 ess single-threa
18a10 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 d was.** previou
18a20 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 sly selected at
18a30 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 compile-time or
18a40 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 54 start-time..** T
18a50 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f he [SQLITE_OPEN_
18a60 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 SHAREDCACHE] fla
18a70 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 g causes the dat
18a80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
18a90 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 to be.** eligib
18aa0 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 le to use [share
18ab0 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 d cache mode], r
18ac0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 egardless of whe
18ad0 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 ther or not shar
18ae0 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 ed.** cache is e
18af0 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 nabled using [sq
18b00 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 lite3_enable_sha
18b10 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 54 red_cache()]. T
18b20 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 he.** [SQLITE_OP
18b30 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d EN_PRIVATECACHE]
18b40 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 flag causes the
18b50 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
18b60 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 tion to not.** p
18b70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 articipate in [s
18b80 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 hared cache mode
18b90 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 ] even if it is
18ba0 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 enabled..**.** I
18bb0 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 f the filename i
18bc0 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 s ":memory:", th
18bd0 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 en a private, te
18be0 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 mporary in-memor
18bf0 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 y database.** is
18c00 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 created for the
18c10 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 connection. Th
18c20 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 is in-memory dat
18c30 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 abase will vanis
18c40 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 h when.** the da
18c50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
18c60 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 n is closed. Fu
18c70 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 ture versions of
18c80 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a SQLite might.**
18c90 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 make use of add
18ca0 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 itional special
18cb0 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 filenames that b
18cc0 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a egin with the ":
18cd0 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 " character..**
18ce0 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 It is recommende
18cf0 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 d that when a da
18d00 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 tabase filename
18d10 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 actually does be
18d20 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a gin with.** a ":
18d30 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 " character you
18d40 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 should prefix th
18d50 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 e filename with
18d60 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 a pathname such
18d70 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 as.** "./" to av
18d80 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a oid ambiguity..*
18d90 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65 *.** If the file
18da0 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 name is an empty
18db0 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 string, then a
18dc0 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 private, tempora
18dd0 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 ry.** on-disk da
18de0 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 tabase will be c
18df0 72 65 61 74 65 64 2e 20 20 54 68 69 73 20 70 72 reated. This pr
18e00 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 ivate database w
18e10 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 ill be.** automa
18e20 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 tically deleted
18e30 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 as soon as the d
18e40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
18e50 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a on is closed..**
18e60 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 .** The fourth p
18e70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
18e80 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 te3_open_v2() is
18e90 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
18ea0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 .** [sqlite3_vfs
18eb0 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 ] object that de
18ec0 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 fines the operat
18ed0 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 ing system inter
18ee0 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 face that.** the
18ef0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f new database co
18f00 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 nnection should
18f10 75 73 65 2e 20 20 49 66 20 74 68 65 20 66 6f 75 use. If the fou
18f20 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 rth parameter is
18f30 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 .** a NULL point
18f40 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 er then the defa
18f50 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 ult [sqlite3_vfs
18f60 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 ] object is used
18f70 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 ..**.** <b>Note
18f80 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 to Windows users
18f90 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 :</b> The encod
18fa0 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 ing used for the
18fb0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 filename argume
18fc0 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 nt.** of sqlite3
18fd0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 _open() and sqli
18fe0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 te3_open_v2() mu
18ff0 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 st be UTF-8, not
19000 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 whatever.** cod
19010 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 epage is current
19020 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c ly defined. Fil
19030 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e enames containin
19040 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a g international.
19050 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 ** characters mu
19060 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 st be converted
19070 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 to UTF-8 prior t
19080 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 o passing them i
19090 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f nto.** sqlite3_o
190a0 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 pen() or sqlite3
190b0 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a _open_v2()..**.*
190c0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
190d0 2a 2a 20 5b 48 31 32 37 30 31 5d 20 5b 48 31 32 ** [H12701] [H12
190e0 37 30 32 5d 20 5b 48 31 32 37 30 33 5d 20 5b 48 702] [H12703] [H
190f0 31 32 37 30 34 5d 20 5b 48 31 32 37 30 36 5d 20 12704] [H12706]
19100 5b 48 31 32 37 30 37 5d 20 5b 48 31 32 37 30 39 [H12707] [H12709
19110 5d 20 5b 48 31 32 37 31 31 5d 0a 2a 2a 20 5b 48 ] [H12711].** [H
19120 31 32 37 31 32 5d 20 5b 48 31 32 37 31 33 5d 20 12712] [H12713]
19130 5b 48 31 32 37 31 34 5d 20 5b 48 31 32 37 31 37 [H12714] [H12717
19140 5d 20 5b 48 31 32 37 31 39 5d 20 5b 48 31 32 37 ] [H12719] [H127
19150 32 31 5d 20 5b 48 31 32 37 32 33 5d 0a 2a 2f 0a 21] [H12723].*/.
19160 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
19170 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 qlite3_open(. c
19180 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e onst char *filen
19190 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 ame, /* Databa
191a0 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 se filename (UTF
191b0 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 -8) */. sqlite3
191c0 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 **ppDb
191d0 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 /* OUT: SQLite
191e0 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a db handle */.);.
191f0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
19200 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 qlite3_open16(.
19210 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c const void *fil
19220 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 ename, /* Data
19230 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 base filename (U
19240 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 TF-16) */. sqli
19250 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 te3 **ppDb
19260 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 /* OUT: SQLi
19270 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a te db handle */.
19280 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
19290 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 t sqlite3_open_v
192a0 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2(. const char
192b0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 *filename, /*
192c0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d Database filenam
192d0 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 e (UTF-8) */. s
192e0 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 qlite3 **ppDb,
192f0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 /* OUT: S
19300 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 QLite db handle
19310 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 */. int flags,
19320 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
19330 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 Flags */. const
19340 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 char *zVfs
19350 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 /* Name of VF
19360 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 S module to use
19370 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.);../*.** CAP
19380 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 I3REF: Error Cod
19390 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 20 es And Messages
193a0 7b 48 31 32 38 30 30 7d 20 3c 53 36 30 32 30 30 {H12800} <S60200
193b0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 >.**.** The sqli
193c0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e te3_errcode() in
193d0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
193e0 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 the numeric [res
193f0 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 ult code] or.**
19400 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
19410 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d code] for the m
19420 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 ost recent faile
19430 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 d sqlite3_* API
19440 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 call.** associat
19450 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 ed with a [datab
19460 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e ase connection].
19470 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 If a prior API
19480 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 call failed.** b
19490 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 ut the most rece
194a0 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 nt API call succ
194b0 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 eeded, the retur
194c0 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 n value from.**
194d0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 sqlite3_errcode(
194e0 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 ) is undefined.
194f0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 The sqlite3_ext
19500 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a ended_errcode().
19510 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 ** interface is
19520 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 the same except
19530 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 that it always r
19540 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b eturns the .** [
19550 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
19560 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 code] even when
19570 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
19580 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 codes are.** dis
19590 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 abled..**.** The
195a0 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 sqlite3_errmsg(
195b0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 ) and sqlite3_er
195c0 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 rmsg16() return
195d0 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 English-language
195e0 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 .** text that de
195f0 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f scribes the erro
19600 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46 r, as either UTF
19610 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 -8 or UTF-16 res
19620 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 pectively..** Me
19630 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 mory to hold the
19640 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 error message s
19650 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 tring is managed
19660 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 internally..**
19670 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
19680 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f does not need to
19690 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 worry about fre
196a0 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e eing the result.
196b0 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 .** However, the
196c0 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 error string mi
196d0 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 ght be overwritt
196e0 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 en or deallocate
196f0 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 d by.** subseque
19700 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 nt calls to othe
19710 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 r SQLite interfa
19720 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a ce functions..**
19730 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 .** When the ser
19740 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 ialized [threadi
19750 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 ng mode] is in u
19760 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 se, it might be
19770 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 the.** case that
19780 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 a second error
19790 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 occurs on a sepa
197a0 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 rate thread in b
197b0 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 etween.** the ti
197c0 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 me of the first
197d0 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 error and the ca
197e0 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 ll to these inte
197f0 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 rfaces..** When
19800 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 that happens, th
19810 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 e second error w
19820 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 ill be reported
19830 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 since these.** i
19840 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 nterfaces always
19850 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 report the most
19860 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 recent result.
19870 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 To avoid.** thi
19880 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 s, each thread c
19890 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 an obtain exclus
198a0 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b ive use of the [
198b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
198c0 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 ion] D.** by inv
198d0 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d oking [sqlite3_m
198e0 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c utex_enter]([sql
198f0 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 ite3_db_mutex](D
19900 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e )) before beginn
19910 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 ing.** to use D
19920 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 and invoking [sq
19930 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 lite3_mutex_leav
19940 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d e]([sqlite3_db_m
19950 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a utex](D)) after.
19960 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 ** all calls to
19970 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c the interfaces l
19980 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 isted here are c
19990 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 ompleted..**.**
199a0 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 If an interface
199b0 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 fails with SQLIT
199c0 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d E_MISUSE, that m
199d0 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 eans the interfa
199e0 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 ce.** was invoke
199f0 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 d incorrectly by
19a00 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
19a10 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c . In that case,
19a20 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f the.** error co
19a30 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d de and message m
19a40 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 ay or may not be
19a50 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 set..**.** Requ
19a60 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
19a70 32 38 30 31 5d 20 5b 48 31 32 38 30 32 5d 20 5b 2801] [H12802] [
19a80 48 31 32 38 30 33 5d 20 5b 48 31 32 38 30 37 5d H12803] [H12807]
19a90 20 5b 48 31 32 38 30 38 5d 20 5b 48 31 32 38 30 [H12808] [H1280
19aa0 39 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 9].*/.SQLITE_API
19ab0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 int sqlite3_err
19ac0 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 code(sqlite3 *db
19ad0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
19ae0 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 t sqlite3_extend
19af0 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 ed_errcode(sqlit
19b00 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f e3 *db);.SQLITE_
19b10 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a API const char *
19b20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 sqlite3_errmsg(s
19b30 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 qlite3*);.SQLITE
19b40 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 _API const void
19b50 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 *sqlite3_errmsg1
19b60 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 6(sqlite3*);../*
19b70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 .** CAPI3REF: SQ
19b80 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 L Statement Obje
19b90 63 74 20 7b 48 31 33 30 30 30 7d 20 3c 48 31 33 ct {H13000} <H13
19ba0 30 31 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 010>.** KEYWORDS
19bb0 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 : {prepared stat
19bc0 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 ement} {prepared
19bd0 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a statements}.**.
19be0 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f ** An instance o
19bf0 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 f this object re
19c00 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c presents a singl
19c10 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e e SQL statement.
19c20 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 .** This object
19c30 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f is variously kno
19c40 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 wn as a "prepare
19c50 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 d statement" or
19c60 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 a.** "compiled S
19c70 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 QL statement" or
19c80 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 simply as a "st
19c90 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 atement"..**.**
19ca0 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 The life of a st
19cb0 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 atement object g
19cc0 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 oes something li
19cd0 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c ke this:.**.** <
19ce0 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 ol>.** <li> Crea
19cf0 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 te the object us
19d00 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 ing [sqlite3_pre
19d10 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 pare_v2()] or a
19d20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 related.**
19d30 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 function..** <li
19d40 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f > Bind values to
19d50 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 [host parameter
19d60 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c s] using the sql
19d70 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a ite3_bind_*().**
19d80 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 interfaces
19d90 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 ..** <li> Run th
19da0 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 e SQL by calling
19db0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
19dc0 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 ] one or more ti
19dd0 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 mes..** <li> Res
19de0 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 et the statement
19df0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
19e00 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f reset()] then go
19e10 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f back.** to
19e20 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 step 2. Do thi
19e30 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 s zero or more t
19e40 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 imes..** <li> De
19e50 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 stroy the object
19e60 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
19e70 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 finalize()]..**
19e80 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 </ol>.**.** Refe
19e90 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 r to documentati
19ea0 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c on on individual
19eb0 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 methods above f
19ec0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a or additional.**
19ed0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f information..*/
19ee0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
19ef0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c sqlite3_stmt sql
19f00 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a ite3_stmt;../*.*
19f10 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d * CAPI3REF: Run-
19f20 74 69 6d 65 20 4c 69 6d 69 74 73 20 7b 48 31 32 time Limits {H12
19f30 37 36 30 7d 20 3c 53 32 30 36 30 30 3e 0a 2a 2a 760} <S20600>.**
19f40 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 .** This interfa
19f50 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 ce allows the si
19f60 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f ze of various co
19f70 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c nstructs to be l
19f80 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 imited.** on a c
19f90 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e onnection by con
19fa0 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 nection basis.
19fb0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 The first parame
19fc0 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 ter is the.** [d
19fd0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
19fe0 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 on] whose limit
19ff0 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 is to be set or
1a000 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a queried. The.**
1a010 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
1a020 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 r is one of the
1a030 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 [limit categorie
1a040 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 s] that define a
1a050 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e .** class of con
1a060 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 structs to be si
1a070 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 ze limited. The
1a080 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
1a090 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c is the.** new l
1a0a0 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f imit for that co
1a0b0 6e 73 74 72 75 63 74 2e 20 20 54 68 65 20 66 75 nstruct. The fu
1a0c0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 nction returns t
1a0d0 68 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 0a 2a 2a he old limit..**
1a0e0 0a 2a 2a 20 49 66 20 74 68 65 20 6e 65 77 20 6c .** If the new l
1a0f0 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 imit is a negati
1a100 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c ve number, the l
1a110 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 imit is unchange
1a120 64 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6c 69 d..** For the li
1a130 6d 69 74 20 63 61 74 65 67 6f 72 79 20 6f 66 20 mit category of
1a140 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 59 5a SQLITE_LIMIT_XYZ
1a150 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 there is a .**
1a160 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 [limits | hard u
1a170 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 pper bound].** s
1a180 65 74 20 62 79 20 61 20 63 6f 6d 70 69 6c 65 2d et by a compile-
1a190 74 69 6d 65 20 43 20 70 72 65 70 72 6f 63 65 73 time C preproces
1a1a0 73 6f 72 20 6d 61 63 72 6f 20 6e 61 6d 65 64 20 sor macro named
1a1b0 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 .** [limits | SQ
1a1c0 4c 49 54 45 5f 4d 41 58 5f 58 59 5a 5d 2e 0a 2a LITE_MAX_XYZ]..*
1a1d0 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 * (The "_LIMIT_"
1a1e0 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 in the name is
1a1f0 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 changed to "_MAX
1a200 5f 22 2e 29 0a 2a 2a 20 41 74 74 65 6d 70 74 73 _".).** Attempts
1a210 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c to increase a l
1a220 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 imit above its h
1a230 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 ard upper bound
1a240 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 are.** silently
1a250 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 truncated to the
1a260 20 68 61 72 64 20 75 70 70 65 72 20 6c 69 6d 69 hard upper limi
1a270 74 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 20 74 69 6d t..**.** Run tim
1a280 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 e limits are int
1a290 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e ended for use in
1a2a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 applications th
1a2b0 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 at manage.** bot
1a2c0 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 h their own inte
1a2d0 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e rnal database an
1a2e0 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 d also databases
1a2f0 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f that are contro
1a300 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 lled.** by untru
1a310 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f sted external so
1a320 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 urces. An examp
1a330 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d le application m
1a340 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 ight be a.** web
1a350 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 browser that ha
1a360 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 s its own databa
1a370 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 ses for storing
1a380 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 history and.** s
1a390 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 eparate database
1a3a0 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 s controlled by
1a3b0 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 JavaScript appli
1a3c0 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 cations download
1a3d0 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e ed.** off the In
1a3e0 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 ternet. The int
1a3f0 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 ernal databases
1a400 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 can be given the
1a410 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 .** large, defau
1a420 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 lt limits. Data
1a430 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 bases managed by
1a440 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 external source
1a450 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 s can.** be give
1a460 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c n much smaller l
1a470 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 imits designed t
1a480 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 o prevent a deni
1a490 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a al of service.**
1a4a0 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f attack. Develo
1a4b0 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 pers might also
1a4c0 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 want to use the
1a4d0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 [sqlite3_set_aut
1a4e0 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e horizer()].** in
1a4f0 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 terface to furth
1a500 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 er control untru
1a510 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 sted SQL. The s
1a520 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 ize of the datab
1a530 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 ase.** created b
1a540 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 y an untrusted s
1a550 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e cript can be con
1a560 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 tained using the
1a570 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f .** [max_page_co
1a580 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a unt] [PRAGMA]..*
1a590 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d *.** New run-tim
1a5a0 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 e limit categori
1a5b0 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 es may be added
1a5c0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
1a5d0 65 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 es..**.** Requir
1a5e0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 37 ements:.** [H127
1a5f0 36 32 5d 20 5b 48 31 32 37 36 36 5d 20 5b 48 31 62] [H12766] [H1
1a600 32 37 36 39 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 2769].*/.SQLITE_
1a610 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
1a620 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 limit(sqlite3*,
1a630 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 int id, int newV
1a640 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 al);../*.** CAPI
1a650 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 3REF: Run-Time L
1a660 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 20 imit Categories
1a670 7b 48 31 32 37 39 30 7d 20 3c 48 31 32 37 36 30 {H12790} <H12760
1a680 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b >.** KEYWORDS: {
1a690 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 limit category}
1a6a0 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 {*limit categori
1a6b0 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 es}.**.** These
1a6c0 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 constants define
1a6d0 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d various perform
1a6e0 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 ance limits.** t
1a6f0 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 hat can be lower
1a700 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 ed at run-time u
1a710 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 sing [sqlite3_li
1a720 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 mit()]..** The s
1a730 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d ynopsis of the m
1a740 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 eanings of the v
1a750 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 arious limits is
1a760 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a shown below..**
1a770 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f Additional info
1a780 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c rmation is avail
1a790 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 able at [limits
1a7a0 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 | Limits in SQLi
1a7b0 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a te]..**.** <dl>.
1a7c0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ** <dt>SQLITE_LI
1a7d0 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a MIT_LENGTH</dt>.
1a7e0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
1a7f0 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 um size of any s
1a800 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 tring or BLOB or
1a810 20 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a table row.<dd>.
1a820 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
1a830 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 _LIMIT_SQL_LENGT
1a840 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 H</dt>.** <dd>Th
1a850 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 e maximum length
1a860 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 of an SQL state
1a870 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ment.</dd>.**.**
1a880 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 <dt>SQLITE_LIMI
1a890 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a T_COLUMN</dt>.**
1a8a0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
1a8b0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
1a8c0 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 ns in a table de
1a8d0 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 finition or in t
1a8e0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 he.** result set
1a8f0 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f of a [SELECT] o
1a900 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 r the maximum nu
1a910 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 mber of columns
1a920 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f in an index.** o
1a930 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 r in an ORDER BY
1a940 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 or GROUP BY cla
1a950 75 73 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 use.</dd>.**.**
1a960 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
1a970 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e _EXPR_DEPTH</dt>
1a980 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
1a990 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 mum depth of the
1a9a0 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 parse tree on a
1a9b0 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f ny expression.</
1a9c0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
1a9d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f LITE_LIMIT_COMPO
1a9e0 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a UND_SELECT</dt>.
1a9f0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
1aa00 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 um number of ter
1aa10 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 ms in a compound
1aa20 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e SELECT statemen
1aa30 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 t.</dd>.**.** <d
1aa40 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 t>SQLITE_LIMIT_V
1aa50 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c DBE_OP</dt>.** <
1aa60 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e dd>The maximum n
1aa70 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 umber of instruc
1aa80 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 tions in a virtu
1aa90 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 al machine progr
1aaa0 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d am.** used to im
1aab0 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 plement an SQL s
1aac0 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a tatement.</dd>.*
1aad0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
1aae0 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 LIMIT_FUNCTION_A
1aaf0 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 RG</dt>.** <dd>T
1ab00 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
1ab10 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f r of arguments o
1ab20 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 n a function.</d
1ab30 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
1ab40 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 ITE_LIMIT_ATTACH
1ab50 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 ED</dt>.** <dd>T
1ab60 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
1ab70 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 r of [ATTACH | a
1ab80 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 ttached database
1ab90 73 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c s].</dd>.**.** <
1aba0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
1abb0 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e LIKE_PATTERN_LEN
1abc0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e GTH</dt>.** <dd>
1abd0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 The maximum leng
1abe0 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 th of the patter
1abf0 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 n argument to th
1ac00 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b e [LIKE] or.** [
1ac10 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e GLOB] operators.
1ac20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
1ac30 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 SQLITE_LIMIT_VAR
1ac40 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 IABLE_NUMBER</dt
1ac50 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
1ac60 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76 imum number of v
1ac70 61 72 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 53 ariables in an S
1ac80 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 QL statement tha
1ac90 74 20 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e t can.** be boun
1aca0 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 d.</dd>.**.** <d
1acb0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 t>SQLITE_LIMIT_T
1acc0 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 RIGGER_DEPTH</dt
1acd0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
1ace0 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 imum depth of re
1acf0 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 cursion for trig
1ad00 67 65 72 73 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f gers.</dd>.** </
1ad10 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 dl>.*/.#define S
1ad20 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 QLITE_LIMIT_LENG
1ad30 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TH
1ad40 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 0.#define
1ad50 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c SQLITE_LIMIT_SQL
1ad60 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 _LENGTH
1ad70 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 1.#define
1ad80 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f SQLITE_LIMIT_CO
1ad90 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 LUMN
1ada0 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 2.#defin
1adb0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 e SQLITE_LIMIT_E
1adc0 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 XPR_DEPTH
1add0 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 3.#defi
1ade0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
1adf0 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 COMPOUND_SELECT
1ae00 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 4.#def
1ae10 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
1ae20 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 _VDBE_OP
1ae30 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 5.#de
1ae40 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
1ae50 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 T_FUNCTION_ARG
1ae60 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 6.#d
1ae70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
1ae80 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 IT_ATTACHED
1ae90 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 7.#
1aea0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
1aeb0 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e MIT_LIKE_PATTERN
1aec0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a _LENGTH 8.
1aed0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
1aee0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 IMIT_VARIABLE_NU
1aef0 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 MBER 9
1af00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1af10 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 LIMIT_TRIGGER_DE
1af20 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 PTH 1
1af30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 0../*.** CAPI3RE
1af40 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 F: Compiling An
1af50 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 SQL Statement {H
1af60 31 33 30 31 30 7d 20 3c 53 31 30 30 30 30 3e 0a 13010} <S10000>.
1af70 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 ** KEYWORDS: {SQ
1af80 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 L statement comp
1af90 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 iler}.**.** To e
1afa0 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 xecute an SQL qu
1afb0 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 ery, it must fir
1afc0 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 st be compiled i
1afd0 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a nto a byte-code.
1afe0 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 ** program using
1aff0 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f one of these ro
1b000 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 utines..**.** Th
1b010 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
1b020 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 , "db", is a [da
1b030 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1b040 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d n] obtained from
1b050 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 a.** prior succ
1b060 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b essful call to [
1b070 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c sqlite3_open()],
1b080 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
1b090 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 2()] or.** [sqli
1b0a0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 te3_open16()].
1b0b0 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e The database con
1b0c0 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 nection must not
1b0d0 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 have been close
1b0e0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 d..**.** The sec
1b0f0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a ond argument, "z
1b100 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 Sql", is the sta
1b110 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d tement to be com
1b120 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a piled, encoded.*
1b130 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d * as either UTF-
1b140 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 8 or UTF-16. Th
1b150 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 e sqlite3_prepar
1b160 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f e() and sqlite3_
1b170 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 prepare_v2().**
1b180 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55 interfaces use U
1b190 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 TF-8, and sqlite
1b1a0 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 3_prepare16() an
1b1b0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 d sqlite3_prepar
1b1c0 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 e16_v2().** use
1b1d0 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 49 66 UTF-16..**.** If
1b1e0 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d the nByte argum
1b1f0 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e ent is less than
1b200 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c zero, then zSql
1b210 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 is read up to t
1b220 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f he.** first zero
1b230 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 49 66 20 terminator. If
1b240 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 nByte is non-neg
1b250 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 ative, then it i
1b260 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a s the maximum.**
1b270 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 number of byte
1b280 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c s read from zSql
1b290 2e 20 20 57 68 65 6e 20 6e 42 79 74 65 20 69 73 . When nByte is
1b2a0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 non-negative, t
1b2b0 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e he.** zSql strin
1b2c0 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 g ends at either
1b2d0 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 the first '\000
1b2e0 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 ' or '\u0000' ch
1b2f0 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 aracter or.** th
1b300 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c e nByte-th byte,
1b310 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 whichever comes
1b320 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 first. If the c
1b330 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 aller knows.** t
1b340 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 hat the supplied
1b350 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 string is nul-t
1b360 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 erminated, then
1b370 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c there is a small
1b380 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 .** performance
1b390 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 advantage to be
1b3a0 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e gained by passin
1b3b0 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d g an nByte param
1b3c0 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 eter that.** is
1b3d0 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d equal to the num
1b3e0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 ber of bytes in
1b3f0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 the input string
1b400 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 <i>including</i
1b410 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 >.** the nul-ter
1b420 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a minator bytes..*
1b430 2a 0a 2a 2a 20 49 66 20 70 7a 54 61 69 6c 20 69 *.** If pzTail i
1b440 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 s not NULL then
1b450 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 *pzTail is made
1b460 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 to point to the
1b470 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 first byte.** pa
1b480 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 st the end of th
1b490 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 e first SQL stat
1b4a0 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 ement in zSql.
1b4b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f These routines o
1b4c0 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 nly.** compile t
1b4d0 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 he first stateme
1b4e0 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a nt in zSql, so *
1b4f0 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 pzTail is left p
1b500 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 ointing to.** wh
1b510 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d at remains uncom
1b520 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 piled..**.** *pp
1b530 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 Stmt is left poi
1b540 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 nting to a compi
1b550 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 led [prepared st
1b560 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 atement] that ca
1b570 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 n be.** executed
1b580 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
1b590 73 74 65 70 28 29 5d 2e 20 20 49 66 20 74 68 65 step()]. If the
1b5a0 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 re is an error,
1b5b0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a *ppStmt is set.*
1b5c0 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74 * to NULL. If t
1b5d0 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f he input text co
1b5e0 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 ntains no SQL (i
1b5f0 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 f the input is a
1b600 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e n empty.** strin
1b610 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 g or a comment)
1b620 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 then *ppStmt is
1b630 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 set to NULL..**
1b640 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 The calling proc
1b650 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 edure is respons
1b660 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e ible for deletin
1b670 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a g the compiled.*
1b680 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 * SQL statement
1b690 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 using [sqlite3_f
1b6a0 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 inalize()] after
1b6b0 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 it has finished
1b6c0 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 with it..** ppS
1b6d0 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e tmt may not be N
1b6e0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 ULL..**.** On su
1b6f0 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f ccess, [SQLITE_O
1b700 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2c 20 K] is returned,
1b710 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 otherwise an [er
1b720 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 ror code] is ret
1b730 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 urned..**.** The
1b740 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
1b750 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 _v2() and sqlite
1b760 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
1b770 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a interfaces are.
1b780 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 ** recommended f
1b790 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 or all new progr
1b7a0 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 ams. The two old
1b7b0 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 er interfaces ar
1b7c0 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f e retained.** fo
1b7d0 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 r backwards comp
1b7e0 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 atibility, but t
1b7f0 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 heir use is disc
1b800 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 ouraged..** In t
1b810 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 he "v2" interfac
1b820 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 es, the prepared
1b830 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 statement.** th
1b840 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 at is returned (
1b850 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d the [sqlite3_stm
1b860 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 t] object) conta
1b870 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 ins a copy of th
1b880 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 e.** original SQ
1b890 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 L text. This cau
1b8a0 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 ses the [sqlite3
1b8b0 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 _step()] interfa
1b8c0 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 ce to.** behave
1b8d0 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 differently in t
1b8e0 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a hree ways:.**.**
1b8f0 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a <ol>.** <li>.**
1b900 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 If the database
1b910 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c schema changes,
1b920 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 instead of retu
1b930 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 rning [SQLITE_SC
1b940 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 HEMA] as it.** a
1b950 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f lways used to do
1b960 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 , [sqlite3_step(
1b970 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 )] will automati
1b980 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 cally recompile
1b990 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 the SQL.** state
1b9a0 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 ment and try to
1b9b0 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 49 run it again. I
1b9c0 66 20 74 68 65 20 73 63 68 65 6d 61 20 68 61 73 f the schema has
1b9d0 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 changed in.** a
1b9e0 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20 way that makes
1b9f0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f the statement no
1ba00 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b longer valid, [
1ba10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
1ba20 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 will still.** re
1ba30 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 turn [SQLITE_SCH
1ba40 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b EMA]. But unlik
1ba50 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 e the legacy beh
1ba60 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53 avior, [SQLITE_S
1ba70 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 CHEMA] is.** now
1ba80 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 a fatal error.
1ba90 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 Calling [sqlite
1baa0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
1bab0 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d again will not m
1bac0 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 ake the.** error
1bad0 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a go away. Note:
1bae0 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 use [sqlite3_er
1baf0 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 rmsg()] to find
1bb00 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74 the text.** of t
1bb10 68 65 20 70 61 72 73 69 6e 67 20 65 72 72 6f 72 he parsing error
1bb20 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e that results in
1bb30 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 an [SQLITE_SCHE
1bb40 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c MA] return..** <
1bb50 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a /li>.**.** <li>.
1bb60 2a 2a 20 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 ** When an error
1bb70 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 occurs, [sqlite
1bb80 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 3_step()] will r
1bb90 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 eturn one of the
1bba0 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 detailed.** [er
1bbb0 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 ror codes] or [e
1bbc0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f xtended error co
1bbd0 64 65 73 5d 2e 20 20 54 68 65 20 6c 65 67 61 63 des]. The legac
1bbe0 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 y behavior was t
1bbf0 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f hat.** [sqlite3_
1bc00 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e step()] would on
1bc10 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 ly return a gene
1bc20 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f ric [SQLITE_ERRO
1bc30 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a R] result code.*
1bc40 2a 20 61 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20 * and you would
1bc50 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 have to make a s
1bc60 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 econd call to [s
1bc70 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
1bc80 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 66 in order.** to f
1bc90 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 ind the underlyi
1bca0 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 ng cause of the
1bcb0 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 problem. With th
1bcc0 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a e "v2" prepare.*
1bcd0 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 * interfaces, th
1bce0 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 e underlying rea
1bcf0 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f son for the erro
1bd00 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d r is returned im
1bd10 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f mediately..** </
1bd20 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a li>.**.** <li>.*
1bd30 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 * ^If the value
1bd40 6f 66 20 61 20 5b 70 61 72 61 6d 65 74 65 72 20 of a [parameter
1bd50 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 | host parameter
1bd60 5d 20 69 6e 20 74 68 65 20 57 48 45 52 45 20 63 ] in the WHERE c
1bd70 6c 61 75 73 65 20 6d 69 67 68 74 0a 2a 2a 20 63 lause might.** c
1bd80 68 61 6e 67 65 20 74 68 65 20 71 75 65 72 79 20 hange the query
1bd90 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 plan for a state
1bda0 6d 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 73 ment, then the s
1bdb0 74 61 74 65 6d 65 6e 74 20 6d 61 79 20 62 65 0a tatement may be.
1bdc0 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ** automatically
1bdd0 20 72 65 63 6f 6d 70 69 6c 65 64 20 28 61 73 20 recompiled (as
1bde0 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65 if there had bee
1bdf0 6e 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 n a schema chang
1be00 65 29 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 e) on the first
1be10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 .** [sqlite3_ste
1be20 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 p()] call follow
1be30 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 20 74 ing any change t
1be40 6f 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 o the .** [sqlit
1be50 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 e3_bind_text | b
1be60 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 65 20 indings] of the
1be70 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a [parameter]. .**
1be80 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a </li>.** </ol>.
1be90 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
1bea0 74 73 3a 0a 2a 2a 20 5b 48 31 33 30 31 31 5d 20 ts:.** [H13011]
1beb0 5b 48 31 33 30 31 32 5d 20 5b 48 31 33 30 31 33 [H13012] [H13013
1bec0 5d 20 5b 48 31 33 30 31 34 5d 20 5b 48 31 33 30 ] [H13014] [H130
1bed0 31 35 5d 20 5b 48 31 33 30 31 36 5d 20 5b 48 31 15] [H13016] [H1
1bee0 33 30 31 39 5d 20 5b 48 31 33 30 32 31 5d 0a 2a 3019] [H13021].*
1bef0 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 *.*/.SQLITE_API
1bf00 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 int sqlite3_prep
1bf10 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a are(. sqlite3 *
1bf20 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f db, /
1bf30 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c * Database handl
1bf40 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
1bf50 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f r *zSql, /
1bf60 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c * SQL statement,
1bf70 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a UTF-8 encoded *
1bf80 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 /. int nByte,
1bf90 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d /* M
1bfa0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
1bfb0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 zSql in bytes.
1bfc0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d */. sqlite3_stm
1bfd0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 t **ppStmt, /*
1bfe0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 OUT: Statement h
1bff0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
1c000 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 char **pzTail
1c010 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 /* OUT: Point
1c020 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 er to unused por
1c030 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a tion of zSql */.
1c040 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
1c050 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 t sqlite3_prepar
1c060 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 e_v2(. sqlite3
1c070 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
1c080 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 /* Database hand
1c090 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 le */. const ch
1c0a0 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 ar *zSql,
1c0b0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 /* SQL statement
1c0c0 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 , UTF-8 encoded
1c0d0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 */. int nByte,
1c0e0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
1c0f0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f Maximum length o
1c100 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e f zSql in bytes.
1c110 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 */. sqlite3_st
1c120 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a mt **ppStmt, /*
1c130 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 OUT: Statement
1c140 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
1c150 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 t char **pzTail
1c160 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e /* OUT: Poin
1c170 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f ter to unused po
1c180 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f rtion of zSql */
1c190 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .);.SQLITE_API i
1c1a0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nt sqlite3_prepa
1c1b0 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 re16(. sqlite3
1c1c0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
1c1d0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 /* Database hand
1c1e0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f le */. const vo
1c1f0 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 id *zSql,
1c200 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 /* SQL statement
1c210 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 , UTF-16 encoded
1c220 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c */. int nByte,
1c230 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
1c240 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 Maximum length
1c250 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 of zSql in bytes
1c260 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 . */. sqlite3_s
1c270 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f tmt **ppStmt, /
1c280 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 * OUT: Statement
1c290 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
1c2a0 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c st void **pzTail
1c2b0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 /* OUT: Poi
1c2c0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 nter to unused p
1c2d0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a ortion of zSql *
1c2e0 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 /.);.SQLITE_API
1c2f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 int sqlite3_prep
1c300 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 are16_v2(. sqli
1c310 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
1c320 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 /* Database
1c330 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
1c340 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 t void *zSql,
1c350 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 /* SQL state
1c360 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 ment, UTF-16 enc
1c370 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 oded */. int nB
1c380 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 yte,
1c390 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e /* Maximum len
1c3a0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 gth of zSql in b
1c3b0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 ytes. */. sqlit
1c3c0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 e3_stmt **ppStmt
1c3d0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 , /* OUT: State
1c3e0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 ment handle */.
1c3f0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a const void **pz
1c400 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a Tail /* OUT:
1c410 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 Pointer to unus
1c420 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 ed portion of zS
1c430 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ql */.);../*.**
1c440 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 CAPI3REF: Retrie
1c450 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 ving Statement S
1c460 51 4c 20 7b 48 31 33 31 30 30 7d 20 3c 48 31 33 QL {H13100} <H13
1c470 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 000>.**.** This
1c480 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 interface can be
1c490 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 used to retriev
1c4a0 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f e a saved copy o
1c4b0 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a f the original.*
1c4c0 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 * SQL text used
1c4d0 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 to create a [pre
1c4e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
1c4f0 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 if that stateme
1c500 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c nt was.** compil
1c510 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 ed using either
1c520 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1c530 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 _v2()] or [sqlit
1c540 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
1c550 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 )]..**.** Requir
1c560 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 31 ements:.** [H131
1c570 30 31 5d 20 5b 48 31 33 31 30 32 5d 20 5b 48 31 01] [H13102] [H1
1c580 33 31 30 33 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 3103].*/.SQLITE_
1c590 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a API const char *
1c5a0 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 sqlite3_sql(sqli
1c5b0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
1c5c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1c5d0 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 F: Dynamically T
1c5e0 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 yped Value Objec
1c5f0 74 20 7b 48 31 35 30 30 30 7d 20 3c 53 32 30 32 t {H15000} <S202
1c600 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 00>.** KEYWORDS:
1c610 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 {protected sqli
1c620 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 te3_value} {unpr
1c630 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
1c640 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c value}.**.** SQL
1c650 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c ite uses the sql
1c660 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
1c670 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 t to represent a
1c680 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 ll values.** tha
1c690 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 t can be stored
1c6a0 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 in a database ta
1c6b0 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 ble. SQLite uses
1c6c0 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a dynamic typing.
1c6d0 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 ** for the value
1c6e0 73 20 69 74 20 73 74 6f 72 65 73 2e 20 56 61 6c s it stores. Val
1c6f0 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 ues stored in sq
1c700 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
1c710 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e cts.** can be in
1c720 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 tegers, floating
1c730 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 point values, s
1c740 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f trings, BLOBs, o
1c750 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e r NULL..**.** An
1c760 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
1c770 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 bject may be eit
1c780 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 her "protected"
1c790 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 or "unprotected"
1c7a0 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 ..** Some interf
1c7b0 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 aces require a p
1c7c0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
1c7d0 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 _value. Other i
1c7e0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c nterfaces.** wil
1c7f0 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 l accept either
1c800 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 a protected or a
1c810 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 n unprotected sq
1c820 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 lite3_value..**
1c830 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 Every interface
1c840 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c that accepts sql
1c850 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d ite3_value argum
1c860 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a ents specifies.*
1c870 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 * whether or not
1c880 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 it requires a p
1c890 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
1c8a0 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 _value..**.** Th
1c8b0 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 e terms "protect
1c8c0 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 ed" and "unprote
1c8d0 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 cted" refer to w
1c8e0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a hether or not.**
1c8f0 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 a mutex is held
1c900 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75 . A internal mu
1c910 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 tex is held for
1c920 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 a protected.** s
1c930 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
1c940 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 ect but no mutex
1c950 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 is held for an
1c960 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 unprotected.** s
1c970 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
1c980 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 ect. If SQLite
1c990 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 is compiled to b
1c9a0 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 e single-threade
1c9b0 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 d.** (with [SQLI
1c9c0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d TE_THREADSAFE=0]
1c9d0 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 and with [sqlit
1c9e0 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d e3_threadsafe()]
1c9f0 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a returning 0).**
1ca00 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 or if SQLite is
1ca10 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 run in one of r
1ca20 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 educed mutex mod
1ca30 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 es .** [SQLITE_C
1ca40 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 ONFIG_SINGLETHRE
1ca50 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 AD] or [SQLITE_C
1ca60 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 ONFIG_MULTITHREA
1ca70 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 D].** then there
1ca80 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 is no distincti
1ca90 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 on between prote
1caa0 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 cted and unprote
1cab0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f cted.** sqlite3_
1cac0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e value objects an
1cad0 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 d they can be us
1cae0 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 ed interchangeab
1caf0 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a ly. However,.**
1cb00 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 for maximum cod
1cb10 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 e portability it
1cb20 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 is recommended
1cb30 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e that application
1cb40 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 s.** still make
1cb50 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 the distinction
1cb60 62 65 74 77 65 65 6e 20 62 65 74 77 65 65 6e 20 between between
1cb70 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e protected and un
1cb80 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c protected.** sql
1cb90 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
1cba0 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 ts even when not
1cbb0 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 strictly requir
1cbc0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ed..**.** The sq
1cbd0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
1cbe0 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 cts that are pas
1cbf0 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 sed as parameter
1cc00 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d s into the.** im
1cc10 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
1cc20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 [application-def
1cc30 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f ined SQL functio
1cc40 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 ns] are protecte
1cc50 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 d..** The sqlite
1cc60 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 3_value object r
1cc70 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 eturned by.** [s
1cc80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 qlite3_column_va
1cc90 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 lue()] is unprot
1cca0 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 ected..** Unprot
1ccb0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
1ccc0 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 lue objects may
1ccd0 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 only be used wit
1cce0 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 h.** [sqlite3_re
1ccf0 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e sult_value()] an
1cd00 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f d [sqlite3_bind_
1cd10 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 value()]..** The
1cd20 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
1cd30 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 blob | sqlite3_v
1cd40 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d alue_type()] fam
1cd50 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 ily of.** interf
1cd60 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f aces require pro
1cd70 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
1cd80 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f alue objects..*/
1cd90 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
1cda0 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 Mem sqlite3_valu
1cdb0 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 e;../*.** CAPI3R
1cdc0 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e EF: SQL Function
1cdd0 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 20 Context Object
1cde0 7b 48 31 36 30 30 31 7d 20 3c 53 32 30 32 30 30 {H16001} <S20200
1cdf0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 >.**.** The cont
1ce00 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 ext in which an
1ce10 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 SQL function exe
1ce20 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 cutes is stored
1ce30 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 in an.** sqlite3
1ce40 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e _context object.
1ce50 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 A pointer to a
1ce60 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 n sqlite3_contex
1ce70 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 t object.** is a
1ce80 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 lways first para
1ce90 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 meter to [applic
1cea0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
1ceb0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a L functions]..**
1cec0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
1ced0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
1cee0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 ction implementa
1cef0 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 tion will pass t
1cf00 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 his.** pointer t
1cf10 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c hrough into call
1cf20 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 s to [sqlite3_re
1cf30 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 sult_int | sqlit
1cf40 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a e3_result()],.**
1cf50 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 [sqlite3_aggreg
1cf60 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 ate_context()],
1cf70 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 [sqlite3_user_da
1cf80 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 ta()],.** [sqlit
1cf90 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 e3_context_db_ha
1cfa0 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 ndle()], [sqlite
1cfb0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 3_get_auxdata()]
1cfc0 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c ,.** and/or [sql
1cfd0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 ite3_set_auxdata
1cfe0 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ()]..*/.typedef
1cff0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 struct sqlite3_c
1d000 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 ontext sqlite3_c
1d010 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ontext;../*.** C
1d020 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 API3REF: Binding
1d030 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 Values To Prepa
1d040 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 20 7b red Statements {
1d050 48 31 33 35 30 30 7d 20 3c 53 37 30 33 30 30 3e H13500} <S70300>
1d060 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 .** KEYWORDS: {h
1d070 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b ost parameter} {
1d080 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d host parameters}
1d090 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 {host parameter
1d0a0 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 name}.** KEYWOR
1d0b0 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 DS: {SQL paramet
1d0c0 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 er} {SQL paramet
1d0d0 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 ers} {parameter
1d0e0 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49 binding}.**.** I
1d0f0 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69 6e 67 n the SQL string
1d100 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 s input to [sqli
1d110 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
1d120 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e ] and its varian
1d130 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 ts,.** literals
1d140 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 may be replaced
1d150 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d by a [parameter]
1d160 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e that matches on
1d170 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a e of following.*
1d180 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a * templates:.**.
1d190 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
1d1a0 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e ?.** <li> ?NNN
1d1b0 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a .** <li> :VVV.*
1d1c0 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 * <li> @VVV.**
1d1d0 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f <li> $VVV.** </
1d1e0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 ul>.**.** In the
1d1f0 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 templates above
1d200 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 , NNN represents
1d210 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 an integer lite
1d220 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 ral,.** and VVV
1d230 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c represents an al
1d240 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 phanumeric ident
1d250 69 66 65 72 2e 20 20 54 68 65 20 76 61 6c 75 65 ifer. The value
1d260 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 s of these.** pa
1d270 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 rameters (also c
1d280 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 alled "host para
1d290 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 meter names" or
1d2a0 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 "SQL parameters"
1d2b0 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 ).** can be set
1d2c0 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 using the sqlite
1d2d0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 3_bind_*() routi
1d2e0 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 nes defined here
1d2f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 ..**.** The firs
1d300 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 t argument to th
1d310 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
1d320 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 () routines is a
1d330 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 lways.** a point
1d340 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 er to the [sqlit
1d350 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 e3_stmt] object
1d360 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a returned from.**
1d370 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1d380 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 e_v2()] or its v
1d390 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 ariants..**.** T
1d3a0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
1d3b0 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 nt is the index
1d3c0 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d of the SQL param
1d3d0 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a eter to be set..
1d3e0 2a 2a 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 ** The leftmost
1d3f0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 SQL parameter ha
1d400 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e s an index of 1.
1d410 20 20 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 When the same
1d420 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 named.** SQL par
1d430 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d ameter is used m
1d440 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 ore than once, s
1d450 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 econd and subseq
1d460 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e uent.** occurren
1d470 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d ces have the sam
1d480 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 e index as the f
1d490 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e irst occurrence.
1d4a0 0a 2a 2a 20 54 68 65 20 69 6e 64 65 78 20 66 6f .** The index fo
1d4b0 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 r named paramete
1d4c0 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 rs can be looked
1d4d0 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a up using the.**
1d4e0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
1d4f0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 arameter_index()
1d500 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64 ] API if desired
1d510 2e 20 20 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 . The index.**
1d520 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d for "?NNN" param
1d530 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c eters is the val
1d540 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 ue of NNN..** Th
1d550 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 e NNN value must
1d560 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e be between 1 an
1d570 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c d the [sqlite3_l
1d580 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d imit()].** param
1d590 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d eter [SQLITE_LIM
1d5a0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 IT_VARIABLE_NUMB
1d5b0 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c ER] (default val
1d5c0 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 ue: 999)..**.**
1d5d0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 The third argume
1d5e0 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 nt is the value
1d5f0 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 to bind to the p
1d600 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 arameter..**.**
1d610 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 In those routine
1d620 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f s that have a fo
1d630 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 urth argument, i
1d640 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a ts value is the.
1d650 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 ** number of byt
1d660 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 es in the parame
1d670 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 ter. To be clea
1d680 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 r: the value is
1d690 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 the.** number of
1d6a0 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e <u>bytes</u> in
1d6b0 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 the value, not
1d6c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 the number of ch
1d6d0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 49 66 20 aracters..** If
1d6e0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
1d6f0 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 eter is negative
1d700 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 , the length of
1d710 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a the string is.**
1d720 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
1d730 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 ytes up to the f
1d740 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e irst zero termin
1d750 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ator..**.** The
1d760 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 fifth argument t
1d770 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 o sqlite3_bind_b
1d780 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 lob(), sqlite3_b
1d790 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a ind_text(), and.
1d7a0 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f ** sqlite3_bind_
1d7b0 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65 text16() is a de
1d7c0 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f structor used to
1d7d0 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 dispose of the
1d7e0 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e BLOB or.** strin
1d7f0 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 g after SQLite h
1d800 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 as finished with
1d810 20 69 74 2e 20 49 66 20 74 68 65 20 66 69 66 74 it. If the fift
1d820 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a h argument is.**
1d830 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c the special val
1d840 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 ue [SQLITE_STATI
1d850 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 C], then SQLite
1d860 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 assumes that the
1d870 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 .** information
1d880 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e is in static, un
1d890 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e managed space an
1d8a0 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 d does not need
1d8b0 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 to be freed..**
1d8c0 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 If the fifth arg
1d8d0 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 ument has the va
1d8e0 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e lue [SQLITE_TRAN
1d8f0 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 SIENT], then.**
1d900 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 SQLite makes its
1d910 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 own private cop
1d920 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d y of the data im
1d930 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 mediately, befor
1d940 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 e.** the sqlite3
1d950 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e _bind_*() routin
1d960 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a e returns..**.**
1d970 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e The sqlite3_bin
1d980 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 d_zeroblob() rou
1d990 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f tine binds a BLO
1d9a0 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 B of length N th
1d9b0 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 at.** is filled
1d9c0 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 41 20 with zeroes. A
1d9d0 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 zeroblob uses a
1d9e0 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 fixed amount of
1d9f0 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 memory.** (just
1da00 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f an integer to ho
1da10 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 ld its size) whi
1da20 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 le it is being p
1da30 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 rocessed..** Zer
1da40 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e oblobs are inten
1da50 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 ded to serve as
1da60 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 placeholders for
1da70 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 BLOBs whose.**
1da80 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 content is later
1da90 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a written using.*
1daa0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f * [sqlite3_blob_
1dab0 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 open | increment
1dac0 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 al BLOB I/O] rou
1dad0 74 69 6e 65 73 2e 0a 2a 2a 20 41 20 6e 65 67 61 tines..** A nega
1dae0 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 tive value for t
1daf0 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 he zeroblob resu
1db00 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 lts in a zero-le
1db10 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a ngth BLOB..**.**
1db20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e The sqlite3_bin
1db30 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 6d d_*() routines m
1db40 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 61 66 ust be called af
1db50 74 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ter.** [sqlite3_
1db60 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 28 61 prepare_v2()] (a
1db70 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 nd its variants)
1db80 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 or [sqlite3_res
1db90 65 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 62 65 66 et()] and.** bef
1dba0 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 ore [sqlite3_ste
1dbb0 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67 p()]..** Binding
1dbc0 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 s are not cleare
1dbd0 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 d by the [sqlite
1dbe0 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 3_reset()] routi
1dbf0 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20 70 ne..** Unbound p
1dc00 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e arameters are in
1dc10 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c terpreted as NUL
1dc20 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 L..**.** These r
1dc30 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b outines return [
1dc40 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 SQLITE_OK] on su
1dc50 63 63 65 73 73 20 6f 72 20 61 6e 20 65 72 72 6f ccess or an erro
1dc60 72 20 63 6f 64 65 20 69 66 0a 2a 2a 20 61 6e 79 r code if.** any
1dc70 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 thing goes wrong
1dc80 2e 20 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 . [SQLITE_RANGE
1dc90 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 ] is returned if
1dca0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a the parameter.*
1dcb0 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f * index is out o
1dcc0 66 20 72 61 6e 67 65 2e 20 20 5b 53 51 4c 49 54 f range. [SQLIT
1dcd0 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 E_NOMEM] is retu
1dce0 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 rned if malloc()
1dcf0 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49 fails..** [SQLI
1dd00 54 45 5f 4d 49 53 55 53 45 5d 20 6d 69 67 68 74 TE_MISUSE] might
1dd10 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 be returned if
1dd20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 these routines a
1dd30 72 65 20 63 61 6c 6c 65 64 20 6f 6e 20 61 0a 2a re called on a.*
1dd40 2a 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e * virtual machin
1dd50 65 20 74 68 61 74 20 69 73 20 74 68 65 20 77 72 e that is the wr
1dd60 6f 6e 67 20 73 74 61 74 65 20 6f 72 20 77 68 69 ong state or whi
1dd70 63 68 20 68 61 73 20 61 6c 72 65 61 64 79 20 62 ch has already b
1dd80 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a een finalized..*
1dd90 2a 20 44 65 74 65 63 74 69 6f 6e 20 6f 66 20 6d * Detection of m
1dda0 69 73 75 73 65 20 69 73 20 75 6e 72 65 6c 69 61 isuse is unrelia
1ddb0 62 6c 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f ble. Applicatio
1ddc0 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 64 65 ns should not de
1ddd0 70 65 6e 64 0a 2a 2a 20 6f 6e 20 53 51 4c 49 54 pend.** on SQLIT
1dde0 45 5f 4d 49 53 55 53 45 20 72 65 74 75 72 6e 73 E_MISUSE returns
1ddf0 2e 20 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 . SQLITE_MISUSE
1de00 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 is intended to
1de10 69 6e 64 69 63 61 74 65 20 61 0a 2a 2a 20 61 20 indicate a.** a
1de20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 74 logic error in t
1de30 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 he application.
1de40 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 Future versions
1de50 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 of SQLite might
1de60 0a 2a 2a 20 70 61 6e 69 63 20 72 61 74 68 65 72 .** panic rather
1de70 20 74 68 61 6e 20 72 65 74 75 72 6e 20 53 51 4c than return SQL
1de80 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 0a 2a ITE_MISUSE..**.*
1de90 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
1dea0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
1deb0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a ter_count()],.**
1dec0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
1ded0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d arameter_name()]
1dee0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 , and [sqlite3_b
1def0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e ind_parameter_in
1df00 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 dex()]..**.** Re
1df10 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
1df20 48 31 33 35 30 36 5d 20 5b 48 31 33 35 30 39 5d H13506] [H13509]
1df30 20 5b 48 31 33 35 31 32 5d 20 5b 48 31 33 35 31 [H13512] [H1351
1df40 35 5d 20 5b 48 31 33 35 31 38 5d 20 5b 48 31 33 5] [H13518] [H13
1df50 35 32 31 5d 20 5b 48 31 33 35 32 34 5d 20 5b 48 521] [H13524] [H
1df60 31 33 35 32 37 5d 0a 2a 2a 20 5b 48 31 33 35 33 13527].** [H1353
1df70 30 5d 20 5b 48 31 33 35 33 33 5d 20 5b 48 31 33 0] [H13533] [H13
1df80 35 33 36 5d 20 5b 48 31 33 35 33 39 5d 20 5b 48 536] [H13539] [H
1df90 31 33 35 34 32 5d 20 5b 48 31 33 35 34 35 5d 20 13542] [H13545]
1dfa0 5b 48 31 33 35 34 38 5d 20 5b 48 31 33 35 35 31 [H13548] [H13551
1dfb0 5d 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ].**.*/.SQLITE_A
1dfc0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 PI int sqlite3_b
1dfd0 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 ind_blob(sqlite3
1dfe0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e _stmt*, int, con
1dff0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c st void*, int n,
1e000 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 void(*)(void*))
1e010 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
1e020 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f sqlite3_bind_do
1e030 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d uble(sqlite3_stm
1e040 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 t*, int, double)
1e050 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
1e060 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e sqlite3_bind_in
1e070 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c t(sqlite3_stmt*,
1e080 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 int, int);.SQLI
1e090 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
1e0a0 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 e3_bind_int64(sq
1e0b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
1e0c0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 , sqlite3_int64)
1e0d0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
1e0e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 sqlite3_bind_nu
1e0f0 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ll(sqlite3_stmt*
1e100 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 , int);.SQLITE_A
1e110 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 PI int sqlite3_b
1e120 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 ind_text(sqlite3
1e130 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e _stmt*, int, con
1e140 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c st char*, int n,
1e150 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 void(*)(void*))
1e160 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
1e170 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 sqlite3_bind_te
1e180 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d xt16(sqlite3_stm
1e190 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 t*, int, const v
1e1a0 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 oid*, int, void(
1e1b0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 *)(void*));.SQLI
1e1c0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
1e1d0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 e3_bind_value(sq
1e1e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
1e1f0 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f , const sqlite3_
1e200 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f value*);.SQLITE_
1e210 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
1e220 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 bind_zeroblob(sq
1e230 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
1e240 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a , int n);../*.**
1e250 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 CAPI3REF: Numbe
1e260 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 r Of SQL Paramet
1e270 65 72 73 20 7b 48 31 33 36 30 30 7d 20 3c 53 37 ers {H13600} <S7
1e280 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 0300>.**.** This
1e290 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 routine can be
1e2a0 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 used to find the
1e2b0 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 number of [SQL
1e2c0 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 parameters].** i
1e2d0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 n a [prepared st
1e2e0 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 atement]. SQL p
1e2f0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f arameters are to
1e300 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 kens of the.** f
1e310 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c orm "?", "?NNN",
1e320 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c ":AAA", "$AAA",
1e330 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 or "@AAA" that
1e340 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 serve as.** plac
1e350 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c eholders for val
1e360 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 ues that are [sq
1e370 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 lite3_bind_blob
1e380 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 | bound].** to t
1e390 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 he parameters at
1e3a0 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a a later time..*
1e3b0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
1e3c0 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 e actually retur
1e3d0 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 ns the index of
1e3e0 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 the largest (rig
1e3f0 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d htmost).** param
1e400 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f eter. For all fo
1e410 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c rms except ?NNN,
1e420 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 this will corre
1e430 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 spond to the.**
1e440 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 number of unique
1e450 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 parameters. If
1e460 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 parameters of t
1e470 68 65 20 3f 4e 4e 4e 20 61 72 65 20 75 73 65 64 he ?NNN are used
1e480 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 ,.** there may b
1e490 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 e gaps in the li
1e4a0 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c st..**.** See al
1e4b0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e so: [sqlite3_bin
1e4c0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 d_blob|sqlite3_b
1e4d0 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 ind()],.** [sqli
1e4e0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
1e4f0 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a er_name()], and.
1e500 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
1e510 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 _parameter_index
1e520 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 ()]..**.** Requi
1e530 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 rements:.** [H13
1e540 36 30 31 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 601].*/.SQLITE_A
1e550 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 PI int sqlite3_b
1e560 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f ind_parameter_co
1e570 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 unt(sqlite3_stmt
1e580 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
1e590 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 REF: Name Of A H
1e5a0 6f 73 74 20 50 61 72 61 6d 65 74 65 72 20 7b 48 ost Parameter {H
1e5b0 31 33 36 32 30 7d 20 3c 53 37 30 33 30 30 3e 0a 13620} <S70300>.
1e5c0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
1e5d0 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 ne returns a poi
1e5e0 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 61 6d 65 nter to the name
1e5f0 20 6f 66 20 74 68 65 20 6e 2d 74 68 0a 2a 2a 20 of the n-th.**
1e600 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 [SQL parameter]
1e610 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 in a [prepared s
1e620 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51 tatement]..** SQ
1e630 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 L parameters of
1e640 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 the form "?NNN"
1e650 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 or ":AAA" or "@A
1e660 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a AA" or "$AAA".**
1e670 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 have a name whi
1e680 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 ch is the string
1e690 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 "?NNN" or ":AAA
1e6a0 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 " or "@AAA" or "
1e6b0 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 $AAA".** respect
1e6c0 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 ively..** In oth
1e6d0 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e er words, the in
1e6e0 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 itial ":" or "$"
1e6f0 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a or "@" or "?".*
1e700 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 * is included as
1e710 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d part of the nam
1e720 65 2e 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 73 e..** Parameters
1e730 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 of the form "?"
1e740 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f without a follo
1e750 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 wing integer hav
1e760 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 e no name.** and
1e770 20 61 72 65 20 61 6c 73 6f 20 72 65 66 65 72 72 are also referr
1e780 65 64 20 74 6f 20 61 73 20 22 61 6e 6f 6e 79 6d ed to as "anonym
1e790 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e ous parameters".
1e7a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 .**.** The first
1e7b0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 host parameter
1e7c0 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 has an index of
1e7d0 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 1, not 0..**.**
1e7e0 49 66 20 74 68 65 20 76 61 6c 75 65 20 6e 20 69 If the value n i
1e7f0 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f s out of range o
1e800 72 20 69 66 20 74 68 65 20 6e 2d 74 68 20 70 61 r if the n-th pa
1e810 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 rameter is.** na
1e820 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c meless, then NUL
1e830 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 L is returned.
1e840 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 The returned str
1e850 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 ing is.** always
1e860 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 in UTF-8 encodi
1e870 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e ng even if the n
1e880 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 amed parameter w
1e890 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 as.** originally
1e8a0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 specified as UT
1e8b0 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 F-16 in [sqlite3
1e8c0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 _prepare16()] or
1e8d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
1e8e0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a pare16_v2()]..**
1e8f0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
1e900 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
1e910 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d |sqlite3_bind()]
1e920 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 ,.** [sqlite3_bi
1e930 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 nd_parameter_cou
1e940 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 nt()], and.** [s
1e950 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
1e960 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a meter_index()]..
1e970 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
1e980 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 32 31 5d 0a ts:.** [H13621].
1e990 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f */.SQLITE_API co
1e9a0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 nst char *sqlite
1e9b0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
1e9c0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 _name(sqlite3_st
1e9d0 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a mt*, int);../*.*
1e9e0 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 * CAPI3REF: Inde
1e9f0 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 x Of A Parameter
1ea00 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 With A Given Na
1ea10 6d 65 20 7b 48 31 33 36 34 30 7d 20 3c 53 37 30 me {H13640} <S70
1ea20 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 300>.**.** Retur
1ea30 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 n the index of a
1ea40 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 n SQL parameter
1ea50 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 given its name.
1ea60 20 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 The.** index va
1ea70 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 lue returned is
1ea80 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 suitable for use
1ea90 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a as the second.*
1eaa0 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b * parameter to [
1eab0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
1eac0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 b|sqlite3_bind()
1ead0 5d 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 ]. A zero.** is
1eae0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 returned if no
1eaf0 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 matching paramet
1eb00 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 54 68 er is found. Th
1eb10 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e e parameter.** n
1eb20 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 ame must be give
1eb30 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 n in UTF-8 even
1eb40 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 if the original
1eb50 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 statement.** was
1eb60 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 prepared from U
1eb70 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 TF-16 text using
1eb80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1eb90 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a e16_v2()]..**.**
1eba0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
1ebb0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 te3_bind_blob|sq
1ebc0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a lite3_bind()],.*
1ebd0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
1ebe0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 parameter_count(
1ebf0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 )], and.** [sqli
1ec00 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
1ec10 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a er_index()]..**.
1ec20 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
1ec30 0a 2a 2a 20 5b 48 31 33 36 34 31 5d 0a 2a 2f 0a .** [H13641].*/.
1ec40 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
1ec50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
1ec60 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 meter_index(sqli
1ec70 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 te3_stmt*, const
1ec80 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a char *zName);..
1ec90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1eca0 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e Reset All Bindin
1ecb0 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 gs On A Prepared
1ecc0 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 36 Statement {H136
1ecd0 36 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 60} <S70300>.**.
1ece0 2a 2a 20 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 ** Contrary to t
1ecf0 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 he intuition of
1ed00 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 many, [sqlite3_r
1ed10 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 eset()] does not
1ed20 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 reset.** the [s
1ed30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
1ed40 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 | bindings] on
1ed50 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
1ed60 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 55 73 65 20 74 ement]..** Use t
1ed70 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 his routine to r
1ed80 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 eset all host pa
1ed90 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c rameters to NULL
1eda0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
1edb0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 36 31 ents:.** [H13661
1edc0 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
1edd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 int sqlite3_clea
1ede0 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 r_bindings(sqlit
1edf0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a e3_stmt*);../*.*
1ee00 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 * CAPI3REF: Numb
1ee10 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e er Of Columns In
1ee20 20 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b 48 A Result Set {H
1ee30 31 33 37 31 30 7d 20 3c 53 31 30 37 30 30 3e 0a 13710} <S10700>.
1ee40 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 **.** Return the
1ee50 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
1ee60 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 ns in the result
1ee70 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 set returned by
1ee80 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the.** [prepare
1ee90 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 54 68 d statement]. Th
1eea0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 is routine retur
1eeb0 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 ns 0 if pStmt is
1eec0 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 an SQL.** state
1eed0 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e ment that does n
1eee0 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 ot return data (
1eef0 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b for example an [
1ef00 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 UPDATE])..**.**
1ef10 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
1ef20 20 5b 48 31 33 37 31 31 5d 0a 2a 2f 0a 53 51 4c [H13711].*/.SQL
1ef30 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
1ef40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 te3_column_count
1ef50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 (sqlite3_stmt *p
1ef60 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Stmt);../*.** CA
1ef70 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e PI3REF: Column N
1ef80 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 ames In A Result
1ef90 20 53 65 74 20 7b 48 31 33 37 32 30 7d 20 3c 53 Set {H13720} <S
1efa0 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 10700>.**.** The
1efb0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 se routines retu
1efc0 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 rn the name assi
1efd0 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 gned to a partic
1efe0 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 ular column.** i
1eff0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 n the result set
1f000 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 of a [SELECT] s
1f010 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 65 20 73 tatement. The s
1f020 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
1f030 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 me().** interfac
1f040 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e e returns a poin
1f050 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 ter to a zero-te
1f060 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 rminated UTF-8 s
1f070 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c tring.** and sql
1f080 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
1f090 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 16() returns a p
1f0a0 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f ointer to a zero
1f0b0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 -terminated.** U
1f0c0 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 54 TF-16 string. T
1f0d0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
1f0e0 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 er is the [prepa
1f0f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a red statement].*
1f100 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 * that implement
1f110 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 s the [SELECT] s
1f120 74 61 74 65 6d 65 6e 74 2e 20 54 68 65 20 73 65 tatement. The se
1f130 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 cond parameter i
1f140 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 s the.** column
1f150 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 6c 65 66 number. The lef
1f160 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 tmost column is
1f170 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 number 0..**.**
1f180 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 The returned str
1f190 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 ing pointer is v
1f1a0 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 alid until eithe
1f1b0 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 r the [prepared
1f1c0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 statement].** is
1f1d0 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 destroyed by [s
1f1e0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
1f1f0 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 )] or until the
1f200 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 next call to.**
1f210 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e sqlite3_column_n
1f220 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 ame() or sqlite3
1f230 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 _column_name16()
1f240 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c on the same col
1f250 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 umn..**.** If sq
1f260 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 lite3_malloc() f
1f270 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 ails during the
1f280 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 processing of ei
1f290 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 ther routine.**
1f2a0 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 (for example dur
1f2b0 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e ing a conversion
1f2c0 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 from UTF-8 to U
1f2d0 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a TF-16) then a.**
1f2e0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 NULL pointer is
1f2f0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
1f300 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 The name of a r
1f310 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 esult column is
1f320 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 the value of the
1f330 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 "AS" clause for
1f340 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c .** that column,
1f350 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 if there is an
1f360 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 AS clause. If t
1f370 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c here is no AS cl
1f380 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ause.** then the
1f390 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c name of the col
1f3a0 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 umn is unspecifi
1f3b0 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 ed and may chang
1f3c0 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 e from.** one re
1f3d0 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 lease of SQLite
1f3e0 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a to the next..**.
1f3f0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
1f400 0a 2a 2a 20 5b 48 31 33 37 32 31 5d 20 5b 48 31 .** [H13721] [H1
1f410 33 37 32 33 5d 20 5b 48 31 33 37 32 34 5d 20 5b 3723] [H13724] [
1f420 48 31 33 37 32 35 5d 20 5b 48 31 33 37 32 36 5d H13725] [H13726]
1f430 20 5b 48 31 33 37 32 37 5d 0a 2a 2f 0a 53 51 4c [H13727].*/.SQL
1f440 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 ITE_API const ch
1f450 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ar *sqlite3_colu
1f460 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f mn_name(sqlite3_
1f470 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 stmt*, int N);.S
1f480 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
1f490 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
1f4a0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 lumn_name16(sqli
1f4b0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e te3_stmt*, int N
1f4c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1f4d0 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 EF: Source Of Da
1f4e0 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 ta In A Query Re
1f4f0 73 75 6c 74 20 7b 48 31 33 37 34 30 7d 20 3c 53 sult {H13740} <S
1f500 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 10700>.**.** The
1f510 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 se routines prov
1f520 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 ide a means to d
1f530 65 74 65 72 6d 69 6e 65 20 77 68 61 74 20 63 6f etermine what co
1f540 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a 2a 20 lumn of what.**
1f550 74 61 62 6c 65 20 69 6e 20 77 68 69 63 68 20 64 table in which d
1f560 61 74 61 62 61 73 65 20 61 20 72 65 73 75 6c 74 atabase a result
1f570 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 of a [SELECT] s
1f580 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66 tatement comes f
1f590 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 rom..** The name
1f5a0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
1f5b0 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c or table or col
1f5c0 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 umn can be retur
1f5d0 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 ned as.** either
1f5e0 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d a UTF-8 or UTF-
1f5f0 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 16 string. The
1f600 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 _database_ routi
1f610 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 nes return.** th
1f620 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c e database name,
1f630 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 the _table_ rou
1f640 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 tines return the
1f650 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 table name, and
1f660 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 .** the origin_
1f670 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
1f680 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e the column name.
1f690 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 .** The returned
1f6a0 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 string is valid
1f6b0 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 until the [prep
1f6c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
1f6d0 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 is destroyed.**
1f6e0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 using [sqlite3_f
1f6f0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e inalize()] or un
1f700 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 til the same inf
1f710 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 ormation is requ
1f720 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 ested.** again i
1f730 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e n a different en
1f740 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 coding..**.** Th
1f750 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 e names returned
1f760 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 are the origina
1f770 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d l un-aliased nam
1f780 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 es of the.** dat
1f790 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e abase, table, an
1f7a0 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 d column..**.**
1f7b0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
1f7c0 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 nt to the follow
1f7d0 69 6e 67 20 63 61 6c 6c 73 20 69 73 20 61 20 5b ing calls is a [
1f7e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1f7f0 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73 65 20 66 75 nt]..** These fu
1f800 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 nctions return i
1f810 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 nformation about
1f820 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
1f830 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 returned by.** t
1f840 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 he statement, wh
1f850 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 ere N is the sec
1f860 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 ond function arg
1f870 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 ument..**.** If
1f880 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 the Nth column r
1f890 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 eturned by the s
1f8a0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 tatement is an e
1f8b0 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 xpression or.**
1f8c0 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 subquery and is
1f8d0 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c not a column val
1f8e0 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 ue, then all of
1f8f0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 these functions
1f900 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 return.** NULL.
1f910 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d These routine m
1f920 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e ight also return
1f930 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 NULL if a memor
1f940 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 y allocation err
1f950 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 4f or.** occurs. O
1f960 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 therwise, they r
1f970 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f eturn the name o
1f980 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 f the attached d
1f990 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 0a 2a atabase, table.*
1f9a0 2a 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 74 68 61 * and column tha
1f9b0 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 t query result c
1f9c0 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 olumn was extrac
1f9d0 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 ted from..**.**
1f9e0 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 As with all othe
1f9f0 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 r SQLite APIs, t
1fa00 68 6f 73 65 20 70 6f 73 74 66 69 78 65 64 20 77 hose postfixed w
1fa10 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a ith "16" return.
1fa20 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 ** UTF-16 encode
1fa30 64 20 73 74 72 69 6e 67 73 2c 20 74 68 65 20 6f d strings, the o
1fa40 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 ther functions r
1fa50 65 74 75 72 6e 20 55 54 46 2d 38 2e 20 7b 45 4e eturn UTF-8. {EN
1fa60 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 41 D}.**.** These A
1fa70 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 PIs are only ava
1fa80 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 ilable if the li
1fa90 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c brary was compil
1faa0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b ed with the.** [
1fab0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f SQLITE_ENABLE_CO
1fac0 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 LUMN_METADATA] C
1fad0 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 -preprocessor sy
1fae0 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a mbol defined..**
1faf0 0a 2a 2a 20 7b 41 31 33 37 35 31 7d 0a 2a 2a 20 .** {A13751}.**
1fb00 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 If two or more t
1fb10 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 hreads call one
1fb20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 or more of these
1fb30 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 routines agains
1fb40 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 t the same.** pr
1fb50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1fb60 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 and column at t
1fb70 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 he same time the
1fb80 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 n the results ar
1fb90 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a e.** undefined..
1fba0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
1fbb0 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 34 31 5d 20 ts:.** [H13741]
1fbc0 5b 48 31 33 37 34 32 5d 20 5b 48 31 33 37 34 33 [H13742] [H13743
1fbd0 5d 20 5b 48 31 33 37 34 34 5d 20 5b 48 31 33 37 ] [H13744] [H137
1fbe0 34 35 5d 20 5b 48 31 33 37 34 36 5d 20 5b 48 31 45] [H13746] [H1
1fbf0 33 37 34 38 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 3748].**.** If t
1fc00 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 wo or more threa
1fc10 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d ds call one or m
1fc20 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ore.** [sqlite3_
1fc30 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f column_database_
1fc40 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 name | column me
1fc50 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 tadata interface
1fc60 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 s].** for the sa
1fc70 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 me [prepared sta
1fc80 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 tement] and resu
1fc90 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 lt column.** at
1fca0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 the same time th
1fcb0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 en the results a
1fcc0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f re undefined..*/
1fcd0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
1fce0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
1fcf0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f column_database_
1fd00 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d name(sqlite3_stm
1fd10 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f t*,int);.SQLITE_
1fd20 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a API const void *
1fd30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
1fd40 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 atabase_name16(s
1fd50 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
1fd60 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
1fd70 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 nst char *sqlite
1fd80 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 3_column_table_n
1fd90 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ame(sqlite3_stmt
1fda0 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 *,int);.SQLITE_A
1fdb0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 PI const void *s
1fdc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 qlite3_column_ta
1fdd0 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 ble_name16(sqlit
1fde0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 e3_stmt*,int);.S
1fdf0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
1fe00 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
1fe10 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 lumn_origin_name
1fe20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
1fe30 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 nt);.SQLITE_API
1fe40 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
1fe50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 te3_column_origi
1fe60 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 n_name16(sqlite3
1fe70 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a _stmt*,int);../*
1fe80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
1fe90 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20 clared Datatype
1fea0 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c Of A Query Resul
1feb0 74 20 7b 48 31 33 37 36 30 7d 20 3c 53 31 30 37 t {H13760} <S107
1fec0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 00>.**.** The fi
1fed0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 rst parameter is
1fee0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
1fef0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 tement]..** If t
1ff00 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 his statement is
1ff10 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 a [SELECT] stat
1ff20 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 ement and the Nt
1ff30 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a h column of the.
1ff40 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 ** returned resu
1ff50 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b lt set of that [
1ff60 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 SELECT] is a tab
1ff70 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 le column (not a
1ff80 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 n.** expression
1ff90 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65 or subquery) the
1ffa0 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 n the declared t
1ffb0 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 ype of the table
1ffc0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 .** column is re
1ffd0 74 75 72 6e 65 64 2e 20 20 49 66 20 74 68 65 20 turned. If the
1ffe0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 Nth column of th
1fff0 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 e result set is
20000 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e an.** expression
20010 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 or subquery, th
20020 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 en a NULL pointe
20030 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a r is returned..*
20040 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 * The returned s
20050 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 tring is always
20060 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 20 7b UTF-8 encoded. {
20070 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 END}.**.** For e
20080 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 xample, given th
20090 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d e database schem
200a0 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 a:.**.** CREATE
200b0 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 TABLE t1(c1 VARI
200c0 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 ANT);.**.** and
200d0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 the following st
200e0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f atement to be co
200f0 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 mpiled:.**.** SE
20100 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 LECT c1 + 1, c1
20110 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 FROM t1;.**.** t
20120 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c his routine woul
20130 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 d return the str
20140 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f ing "VARIANT" fo
20150 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 r the second res
20160 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 ult.** column (i
20170 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c ==1), and a NULL
20180 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 pointer for the
20190 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f first result co
201a0 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a lumn (i==0)..**.
201b0 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 ** SQLite uses d
201c0 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 ynamic run-time
201d0 74 79 70 69 6e 67 2e 20 20 53 6f 20 6a 75 73 74 typing. So just
201e0 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d because a colum
201f0 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 n.** is declared
20200 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 to contain a pa
20210 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f rticular type do
20220 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 es not mean that
20230 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f the.** data sto
20240 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 red in that colu
20250 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 mn is of the dec
20260 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c lared type. SQL
20270 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 ite is.** strong
20280 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 ly typed, but th
20290 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 e typing is dyna
202a0 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 mic not static.
202b0 20 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f Type.** is asso
202c0 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 ciated with indi
202d0 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e vidual values, n
202e0 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 ot with the cont
202f0 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 ainers.** used t
20300 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c o hold those val
20310 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 ues..**.** Requi
20320 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 rements:.** [H13
20330 37 36 31 5d 20 5b 48 31 33 37 36 32 5d 20 5b 48 761] [H13762] [H
20340 31 33 37 36 33 5d 0a 2a 2f 0a 53 51 4c 49 54 45 13763].*/.SQLITE
20350 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 _API const char
20360 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
20370 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 decltype(sqlite3
20380 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c _stmt*,int);.SQL
20390 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f ITE_API const vo
203a0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 id *sqlite3_colu
203b0 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 mn_decltype16(sq
203c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
203d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
203e0 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 F: Evaluate An S
203f0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 QL Statement {H1
20400 33 32 30 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 3200} <S10000>.*
20410 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 *.** After a [pr
20420 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
20430 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 ] has been prepa
20440 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 red using either
20450 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
20460 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 pare_v2()] or [s
20470 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
20480 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 _v2()] or one of
20490 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 the legacy.** i
204a0 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 nterfaces [sqlit
204b0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 e3_prepare()] or
204c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
204d0 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e e16()], this fun
204e0 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 ction.** must be
204f0 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d called one or m
20500 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 ore times to eva
20510 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d luate the statem
20520 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 ent..**.** The d
20530 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 etails of the be
20540 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 havior of the sq
20550 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 lite3_step() int
20560 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a erface depend.**
20570 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 on whether the
20580 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 statement was pr
20590 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 epared using the
205a0 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 newer "v2" inte
205b0 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 rface.** [sqlite
205c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
205d0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 and [sqlite3_pre
205e0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 pare16_v2()] or
205f0 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 the older legacy
20600 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 .** interface [s
20610 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
20620 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 ] and [sqlite3_p
20630 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 repare16()]. Th
20640 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 e use of the.**
20650 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 new "v2" interfa
20660 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 ce is recommende
20670 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 d for new applic
20680 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c ations but the l
20690 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 egacy.** interfa
206a0 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 ce will continue
206b0 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 to be supported
206c0 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 6c ..**.** In the l
206d0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c egacy interface,
206e0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
206f0 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 e will be either
20700 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a [SQLITE_BUSY],.
20710 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d ** [SQLITE_DONE]
20720 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 , [SQLITE_ROW],
20730 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 [SQLITE_ERROR],
20740 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 or [SQLITE_MISUS
20750 45 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 E]..** With the
20760 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 "v2" interface,
20770 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 any of the other
20780 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 [result codes]
20790 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 or.** [extended
207a0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 result codes] mi
207b0 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 ght be returned
207c0 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b as well..**.** [
207d0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 SQLITE_BUSY] mea
207e0 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 ns that the data
207f0 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 base engine was
20800 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 unable to acquir
20810 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 e the.** databas
20820 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 e locks it needs
20830 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 to do its job.
20840 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e If the statemen
20850 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a t is a [COMMIT].
20860 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 ** or occurs out
20870 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 side of an expli
20880 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c cit transaction,
20890 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 then you can re
208a0 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 try the.** state
208b0 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 ment. If the st
208c0 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 atement is not a
208d0 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 [COMMIT] and oc
208e0 63 75 72 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a curs within a.**
208f0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 explicit transa
20900 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 ction then you s
20910 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 hould rollback t
20920 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 he transaction b
20930 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 efore.** continu
20940 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 ing..**.** [SQLI
20950 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 TE_DONE] means t
20960 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e hat the statemen
20970 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 t has finished e
20980 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 xecuting.** succ
20990 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 essfully. sqlit
209a0 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 e3_step() should
209b0 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 not be called a
209c0 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 gain on this vir
209d0 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 tual.** machine
209e0 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 without first ca
209f0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 lling [sqlite3_r
20a00 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 eset()] to reset
20a10 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 the virtual.**
20a20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 machine back to
20a30 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 its initial stat
20a40 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 e..**.** If the
20a50 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 SQL statement be
20a60 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74 ing executed ret
20a70 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 urns any data, t
20a80 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d hen [SQLITE_ROW]
20a90 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 .** is returned
20aa0 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 each time a new
20ab0 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 row of data is r
20ac0 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 eady for process
20ad0 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 ing by the.** ca
20ae0 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 ller. The values
20af0 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64 may be accessed
20b00 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 using the [colu
20b10 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 mn access functi
20b20 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 ons]..** sqlite3
20b30 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 _step() is calle
20b40 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 d again to retri
20b50 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 eve the next row
20b60 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 of data..**.**
20b70 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d [SQLITE_ERROR] m
20b80 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d eans that a run-
20b90 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 time error (such
20ba0 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 as a constraint
20bb0 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 .** violation) h
20bc0 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 as occurred. sq
20bd0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f lite3_step() sho
20be0 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 uld not be calle
20bf0 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 d again on.** th
20c00 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 e VM. More infor
20c10 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f mation may be fo
20c20 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b und by calling [
20c30 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 sqlite3_errmsg()
20c40 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 6c ]..** With the l
20c50 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c egacy interface,
20c60 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 a more specific
20c70 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 error code (for
20c80 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 example,.** [SQ
20c90 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c LITE_INTERRUPT],
20ca0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d [SQLITE_SCHEMA]
20cb0 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 , [SQLITE_CORRUP
20cc0 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 T], and so forth
20cd0 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 ).** can be obta
20ce0 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 ined by calling
20cf0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
20d00 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 ] on the.** [pre
20d10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
20d20 2e 20 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 . In the "v2" i
20d30 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 nterface,.** the
20d40 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 more specific e
20d50 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 rror code is ret
20d60 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 urned directly b
20d70 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 y sqlite3_step()
20d80 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ..**.** [SQLITE_
20d90 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 MISUSE] means th
20da0 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 at the this rout
20db0 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 ine was called i
20dc0 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a nappropriately..
20dd0 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61 ** Perhaps it wa
20de0 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 s called on a [p
20df0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
20e00 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 t] that has.** a
20e10 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c lready been [sql
20e20 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 ite3_finalize |
20e30 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e finalized] or on
20e40 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a one that had.**
20e50 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 previously retu
20e60 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 rned [SQLITE_ERR
20e70 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 OR] or [SQLITE_D
20e80 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 ONE]. Or it cou
20e90 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 ld.** be the cas
20ea0 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 e that the same
20eb0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
20ec0 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 ion is being use
20ed0 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d d by two or.** m
20ee0 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 ore threads at t
20ef0 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 he same moment i
20f00 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 n time..**.** <b
20f10 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 >Goofy Interface
20f20 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 Alert:</b> In t
20f30 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 he legacy interf
20f40 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 ace, the sqlite3
20f50 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 _step().** API a
20f60 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 lways returns a
20f70 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f generic error co
20f80 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f de, [SQLITE_ERRO
20f90 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e R], following an
20fa0 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 y.** error other
20fb0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 than [SQLITE_BU
20fc0 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f SY] and [SQLITE_
20fd0 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 MISUSE]. You mu
20fe0 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 st call.** [sqli
20ff0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 te3_reset()] or
21000 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
21010 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f e()] in order to
21020 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 find one of the
21030 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 .** specific [er
21040 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 ror codes] that
21050 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 better describes
21060 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 the error..** W
21070 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 e admit that thi
21080 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 s is a goofy des
21090 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 ign. The proble
210a0 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 m has been fixed
210b0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 .** with the "v2
210c0 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 " interface. If
210d0 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c you prepare all
210e0 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 of your SQL sta
210f0 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 tements.** using
21100 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 either [sqlite3
21110 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
21120 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 r [sqlite3_prepa
21130 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 re16_v2()] inste
21140 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 ad.** of the leg
21150 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 acy [sqlite3_pre
21160 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c pare()] and [sql
21170 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
21180 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a ] interfaces,.**
21190 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 then the more s
211a0 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 pecific [error c
211b0 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e odes] are return
211c0 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 ed directly.** b
211d0 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 y sqlite3_step()
211e0 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 . The use of th
211f0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 e "v2" interface
21200 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e is recommended.
21210 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
21220 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 32 30 32 5d nts:.** [H13202]
21230 20 5b 48 31 35 33 30 34 5d 20 5b 48 31 35 33 30 [H15304] [H1530
21240 36 5d 20 5b 48 31 35 33 30 38 5d 20 5b 48 31 35 6] [H15308] [H15
21250 33 31 30 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 310].*/.SQLITE_A
21260 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 PI int sqlite3_s
21270 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 tep(sqlite3_stmt
21280 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
21290 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 REF: Number of c
212a0 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 olumns in a resu
212b0 6c 74 20 73 65 74 20 7b 48 31 33 37 37 30 7d 20 lt set {H13770}
212c0 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 <S10700>.**.** R
212d0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
212e0 72 20 6f 66 20 76 61 6c 75 65 73 20 69 6e 20 74 r of values in t
212f0 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f he current row o
21300 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 f the result set
21310 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
21320 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 37 31 ents:.** [H13771
21330 5d 20 5b 48 31 33 37 37 32 5d 0a 2a 2f 0a 53 51 ] [H13772].*/.SQ
21340 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
21350 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 ite3_data_count(
21360 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 sqlite3_stmt *pS
21370 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tmt);../*.** CAP
21380 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 I3REF: Fundament
21390 61 6c 20 44 61 74 61 74 79 70 65 73 20 7b 48 31 al Datatypes {H1
213a0 30 32 36 35 7d 20 3c 53 31 30 31 31 30 3e 3c 53 0265} <S10110><S
213b0 31 30 31 32 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 10120>.** KEYWOR
213c0 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a DS: SQLITE_TEXT.
213d0 2a 2a 0a 2a 2a 20 7b 48 31 30 32 36 36 7d 20 45 **.** {H10266} E
213e0 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 very value in SQ
213f0 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 Lite has one of
21400 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c five fundamental
21410 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a datatypes:.**.*
21420 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 * <ul>.** <li> 6
21430 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 4-bit signed int
21440 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d eger.** <li> 64-
21450 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e bit IEEE floatin
21460 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a g point number.*
21470 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a * <li> string.**
21480 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c <li> BLOB.** <l
21490 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e i> NULL.** </ul>
214a0 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 {END}.**.** The
214b0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 se constants are
214c0 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 codes for each
214d0 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a of those types..
214e0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 **.** Note that
214f0 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 the SQLITE_TEXT
21500 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 constant was als
21510 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 o used in SQLite
21520 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f version 2.** fo
21530 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 r a completely d
21540 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 ifferent meaning
21550 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 . Software that
21560 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 links against b
21570 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 oth.** SQLite ve
21580 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 rsion 2 and SQLi
21590 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f te version 3 sho
215a0 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f uld use SQLITE3_
215b0 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c TEXT, not.** SQL
215c0 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 ITE_TEXT..*/.#de
215d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 fine SQLITE_INTE
215e0 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 GER 1.#define S
215f0 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 QLITE_FLOAT 2
21600 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
21610 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 BLOB 4.#defi
21620 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 ne SQLITE_NULL
21630 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 5.#ifdef SQLI
21640 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 TE_TEXT.# undef
21650 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 SQLITE_TEXT.#els
21660 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 e.# define SQLIT
21670 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e E_TEXT 3.#en
21680 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 dif.#define SQLI
21690 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a TE3_TEXT 3..
216a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
216b0 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 Result Values Fr
216c0 6f 6d 20 41 20 51 75 65 72 79 20 7b 48 31 33 38 om A Query {H138
216d0 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 00} <S10700>.**
216e0 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d KEYWORDS: {colum
216f0 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f n access functio
21700 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ns}.**.** These
21710 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 routines form th
21720 65 20 22 72 65 73 75 6c 74 20 73 65 74 20 71 75 e "result set qu
21730 65 72 79 22 20 69 6e 74 65 72 66 61 63 65 2e 0a ery" interface..
21740 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
21750 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f ines return info
21760 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 rmation about a
21770 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 single column of
21780 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 the current.**
21790 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 result row of a
217a0 71 75 65 72 79 2e 20 20 49 6e 20 65 76 65 72 79 query. In every
217b0 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 case the first
217c0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f argument is a po
217d0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 inter.** to the
217e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
217f0 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 ent] that is bei
21800 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 ng evaluated (th
21810 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a e [sqlite3_stmt*
21820 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 ].** that was re
21830 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c turned from [sql
21840 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
21850 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 )] or one of its
21860 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e variants).** an
21870 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 d the second arg
21880 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 ument is the ind
21890 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e ex of the column
218a0 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 for which infor
218b0 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 mation.** should
218c0 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20 54 be returned. T
218d0 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 he leftmost colu
218e0 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 mn of the result
218f0 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 set has the ind
21900 65 78 20 30 2e 0a 2a 2a 20 54 68 65 20 6e 75 6d ex 0..** The num
21910 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 ber of columns i
21920 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e n the result can
21930 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 be determined u
21940 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 sing.** [sqlite3
21950 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d _column_count()]
21960 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 ..**.** If the S
21970 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 QL statement doe
21980 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 s not currently
21990 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 point to a valid
219a0 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a row, or if the.
219b0 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 ** column index
219c0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c is out of range,
219d0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 the result is u
219e0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 ndefined..** The
219f0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 se routines may
21a00 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 only be called w
21a10 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 hen the most rec
21a20 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b ent call to.** [
21a30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
21a40 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 has returned [SQ
21a50 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 LITE_ROW] and ne
21a60 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 ither.** [sqlite
21a70 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 3_reset()] nor [
21a80 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
21a90 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 ()] have been ca
21aa0 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c lled subsequentl
21ab0 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 y..** If any of
21ac0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 these routines a
21ad0 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 re called after
21ae0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
21af0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ] or.** [sqlite3
21b00 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 _finalize()] or
21b10 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 after [sqlite3_s
21b20 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 tep()] has retur
21b30 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 ned.** something
21b40 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c other than [SQL
21b50 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 ITE_ROW], the re
21b60 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 sults are undefi
21b70 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 ned..** If [sqli
21b80 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b te3_step()] or [
21b90 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
21ba0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e or [sqlite3_fin
21bb0 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 alize()].** are
21bc0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 called from a di
21bd0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 fferent thread w
21be0 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 hile any of thes
21bf0 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 e routines.** ar
21c00 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 e pending, then
21c10 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 the results are
21c20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
21c30 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c The sqlite3_col
21c40 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 umn_type() routi
21c50 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a ne returns the.*
21c60 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 * [SQLITE_INTEGE
21c70 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 R | datatype cod
21c80 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 e] for the initi
21c90 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 al data type.**
21ca0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f of the result co
21cb0 6c 75 6d 6e 2e 20 20 54 68 65 20 72 65 74 75 72 lumn. The retur
21cc0 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 ned value is one
21cd0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 of [SQLITE_INTE
21ce0 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 GER],.** [SQLITE
21cf0 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 _FLOAT], [SQLITE
21d00 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f _TEXT], [SQLITE_
21d10 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 BLOB], or [SQLIT
21d20 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 E_NULL]. The va
21d30 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 lue.** returned
21d40 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d by sqlite3_colum
21d50 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 n_type() is only
21d60 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e meaningful if n
21d70 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 o type.** conver
21d80 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 sions have occur
21d90 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64 red as described
21da0 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 below. After a
21db0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e type conversion
21dc0 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 ,.** the value r
21dd0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
21de0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 e3_column_type()
21df0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 is undefined.
21e00 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f Future.** versio
21e10 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 ns of SQLite may
21e20 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 change the beha
21e30 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f vior of sqlite3_
21e40 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a column_type().**
21e50 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 following a typ
21e60 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a e conversion..**
21e70 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c .** If the resul
21e80 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 t is a BLOB or U
21e90 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e TF-8 string then
21ea0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c the sqlite3_col
21eb0 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 umn_bytes().** r
21ec0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 outine returns t
21ed0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
21ee0 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 es in that BLOB
21ef0 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49 66 or string..** If
21f00 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 the result is a
21f10 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 UTF-16 string,
21f20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
21f30 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 umn_bytes() conv
21f40 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 erts.** the stri
21f50 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 ng to UTF-8 and
21f60 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 then returns the
21f70 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
21f80 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 ..** If the resu
21f90 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 lt is a numeric
21fa0 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 value then sqlit
21fb0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
21fc0 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 ) uses.** [sqlit
21fd0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 e3_snprintf()] t
21fe0 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 o convert that v
21ff0 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 alue to a UTF-8
22000 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 string and retur
22010 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 ns.** the number
22020 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 of bytes in tha
22030 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68 65 t string..** The
22040 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
22050 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 does not include
22060 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e the zero termin
22070 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a ator at the end.
22080 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 ** of the string
22090 2e 20 20 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 . For clarity:
220a0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
220b0 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 ed is the number
220c0 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 of.** bytes in
220d0 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 the string, not
220e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 the number of ch
220f0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 aracters..**.**
22100 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 Strings returned
22110 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by sqlite3_colu
22120 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 mn_text() and sq
22130 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
22140 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 t16(),.** even e
22150 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 mpty strings, ar
22160 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 74 65 e always zero te
22170 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20 72 rminated. The r
22180 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 eturn.** value f
22190 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 rom sqlite3_colu
221a0 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 mn_blob() for a
221b0 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 zero-length BLOB
221c0 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 is an arbitrary
221d0 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f 73 .** pointer, pos
221e0 73 69 62 6c 79 20 65 76 65 6e 20 61 20 4e 55 4c sibly even a NUL
221f0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a L pointer..**.**
22200 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c The sqlite3_col
22210 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 6f umn_bytes16() ro
22220 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 utine is similar
22230 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 to sqlite3_colu
22240 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62 75 mn_bytes().** bu
22250 74 20 6c 65 61 76 65 73 20 74 68 65 20 72 65 73 t leaves the res
22260 75 6c 74 20 69 6e 20 55 54 46 2d 31 36 20 69 6e ult in UTF-16 in
22270 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 native byte ord
22280 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54 er instead of UT
22290 46 2d 38 2e 0a 2a 2a 20 54 68 65 20 7a 65 72 6f F-8..** The zero
222a0 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e terminator is n
222b0 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 ot included in t
222c0 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a his count..**.**
222d0 20 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 The object retu
222e0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 rned by [sqlite3
222f0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d _column_value()]
22300 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f is an.** [unpro
22310 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
22320 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 alue] object. A
22330 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 n unprotected sq
22340 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
22350 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 ct.** may only b
22360 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c e used with [sql
22370 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 ite3_bind_value(
22380 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
22390 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e result_value()].
223a0 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 .** If the [unpr
223b0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
223c0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 value] object re
223d0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 turned by.** [sq
223e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c lite3_column_val
223f0 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e ue()] is used in
22400 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 any other way,
22410 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a including calls.
22420 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c ** to routines l
22430 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c ike [sqlite3_val
22440 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 ue_int()], [sqli
22450 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 te3_value_text()
22460 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 ],.** or [sqlite
22470 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 3_value_bytes()]
22480 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 , then the behav
22490 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ior is undefined
224a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f ..**.** These ro
224b0 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 utines attempt t
224c0 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 o convert the va
224d0 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 lue where approp
224e0 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 riate. For.** e
224f0 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 xample, if the i
22500 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e nternal represen
22510 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 tation is FLOAT
22520 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c and a text resul
22530 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 t.** is requeste
22540 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 d, [sqlite3_snpr
22550 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 intf()] is used
22560 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 internally to pe
22570 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e rform the.** con
22580 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 version automati
22590 63 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c cally. The foll
225a0 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 owing table deta
225b0 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 ils the conversi
225c0 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 ons.** that are
225d0 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c applied:.**.** <
225e0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c blockquote>.** <
225f0 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 table border="1"
22600 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e >.** <tr><th> In
22610 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c ternal<br>Type <
22620 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 th> Requested<br
22630 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 >Type <th> Conv
22640 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 ersion.**.** <tr
22650 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c ><td> NULL <
22660 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 td> INTEGER <t
22670 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a d> Result is 0.*
22680 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c * <tr><td> NULL
22690 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 <td> FLOAT
226a0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 <td> Result i
226b0 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 s 0.0.** <tr><td
226c0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 > NULL <td>
226d0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 TEXT <td> R
226e0 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f esult is NULL po
226f0 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 inter.** <tr><td
22700 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 > NULL <td>
22710 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 BLOB <td> R
22720 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f esult is NULL po
22730 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 inter.** <tr><td
22740 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 > INTEGER <td>
22750 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 FLOAT <td> C
22760 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 onvert from inte
22770 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 ger to float.**
22780 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 <tr><td> INTEGER
22790 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 <td> TEXT
227a0 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 <td> ASCII rend
227b0 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 ering of the int
227c0 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e eger.** <tr><td>
227d0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 INTEGER <td>
227e0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 BLOB <td> Sa
227f0 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 me as INTEGER->T
22800 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 EXT.** <tr><td>
22810 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e FLOAT <td> IN
22820 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e TEGER <td> Con
22830 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 vert from float
22840 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 to integer.** <t
22850 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 r><td> FLOAT
22860 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c <td> TEXT <
22870 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 td> ASCII render
22880 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 ing of the float
22890 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c .** <tr><td> FL
228a0 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f OAT <td> BLO
228b0 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 B <td> Same a
228c0 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a s FLOAT->TEXT.**
228d0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 <tr><td> TEXT
228e0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 <td> INTEGER
228f0 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28 <td> Use atoi(
22900 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 ).** <tr><td> T
22910 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f EXT <td> FLO
22920 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61 AT <td> Use a
22930 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 tof().** <tr><td
22940 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 > TEXT <td>
22950 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e BLOB <td> N
22960 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e o change.** <tr>
22970 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 <td> BLOB <t
22980 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 d> INTEGER <td
22990 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 > Convert to TEX
229a0 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28 T then use atoi(
229b0 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 ).** <tr><td> B
229c0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f LOB <td> FLO
229d0 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 AT <td> Conve
229e0 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 rt to TEXT then
229f0 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 use atof().** <t
22a00 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 r><td> BLOB
22a10 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c <td> TEXT <
22a20 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 td> Add a zero t
22a30 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 erminator if nee
22a40 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a ded.** </table>.
22a50 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e ** </blockquote>
22a60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 .**.** The table
22a70 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 above makes ref
22a80 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 erence to standa
22a90 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e rd C library fun
22aa0 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a ctions atoi().**
22ab0 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 and atof(). SQ
22ac0 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 Lite does not re
22ad0 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 ally use these f
22ae0 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 unctions. It ha
22af0 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 s its.** own equ
22b00 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c ivalent internal
22b10 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 routines. The
22b20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 atoi() and atof(
22b30 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 ) names are.** u
22b40 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 sed in the table
22b50 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 for brevity and
22b60 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72 because they ar
22b70 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f e familiar to mo
22b80 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d st.** C programm
22b90 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 ers..**.** Note
22ba0 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 that when type c
22bb0 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 onversions occur
22bc0 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 , pointers retur
22bd0 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 ned by prior.**
22be0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 calls to sqlite3
22bf0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 _column_blob(),
22c00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
22c10 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a ext(), and/or.**
22c20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
22c30 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 text16() may be
22c40 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 invalidated..**
22c50 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 Type conversions
22c60 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 and pointer inv
22c70 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 alidations might
22c80 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 occur.** in the
22c90 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 following cases
22ca0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
22cb0 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c <li> The initial
22cc0 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c content is a BL
22cd0 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 OB and sqlite3_c
22ce0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a olumn_text() or.
22cf0 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f ** sqlite3_
22d00 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 column_text16()
22d10 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 is called. A ze
22d20 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 ro-terminator mi
22d30 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 ght.** need
22d40 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 to be added to
22d50 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e the string.</li>
22d60 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 .** <li> The ini
22d70 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 tial content is
22d80 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 UTF-8 text and s
22d90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
22da0 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 tes16() or.**
22db0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d sqlite3_colum
22dc0 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 n_text16() is ca
22dd0 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 lled. The conte
22de0 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 nt must be conve
22df0 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 rted.** to
22e00 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 UTF-16.</li>.**
22e10 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c <li> The initial
22e20 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d content is UTF-
22e30 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 16 text and sqli
22e40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
22e50 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 () or.** sq
22e60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
22e70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 t() is called.
22e80 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 The content must
22e90 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a be converted.**
22ea0 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c to UTF-8.<
22eb0 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a /li>.** </ul>.**
22ec0 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e 73 20 .** Conversions
22ed0 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 between UTF-16be
22ee0 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 and UTF-16le ar
22ef0 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e e always done in
22f00 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a place and do.**
22f10 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 not invalidate
22f20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c a prior pointer,
22f30 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 though of cours
22f40 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 e the content of
22f50 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 the buffer.** t
22f60 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f hat the prior po
22f70 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f 20 inter points to
22f80 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d will have been m
22f90 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 odified. Other
22fa0 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 kinds.** of conv
22fb0 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 ersion are done
22fc0 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 in place when it
22fd0 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 is possible, bu
22fe0 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 t sometimes they
22ff0 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 .** are not poss
23000 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 ible and in thos
23010 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f e cases prior po
23020 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c inters are inval
23030 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 idated..**.** Th
23040 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 e safest and eas
23050 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 iest to remember
23060 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e policy is to in
23070 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 voke these routi
23080 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 nes.** in one of
23090 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 the following w
230a0 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a ays:.**.** <ul>.
230b0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f ** <li>sqlite3_
230c0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f column_text() fo
230d0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 llowed by sqlite
230e0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
230f0 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 </li>.** <li>sq
23100 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
23110 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 b() followed by
23120 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
23130 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 ytes()</li>.**
23140 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 <li>sqlite3_colu
23150 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c mn_text16() foll
23160 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f owed by sqlite3_
23170 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
23180 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a </li>.** </ul>.*
23190 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f *.** In other wo
231a0 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 rds, you should
231b0 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c call sqlite3_col
231c0 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 umn_text(),.** s
231d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
231e0 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 ob(), or sqlite3
231f0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
23200 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 first to force
23210 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e the result.** in
23220 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66 to the desired f
23230 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f ormat, then invo
23240 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d ke sqlite3_colum
23250 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 n_bytes() or.**
23260 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
23270 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 ytes16() to find
23280 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 the size of the
23290 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 result. Do not
232a0 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f mix calls.** to
232b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
232c0 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 text() or sqlite
232d0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 3_column_blob()
232e0 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a with calls to.**
232f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
23300 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 bytes16(), and d
23310 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 o not mix calls
23320 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d to sqlite3_colum
23330 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 n_text16().** wi
23340 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 th calls to sqli
23350 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
23360 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f ()..**.** The po
23370 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 inters returned
23380 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 are valid until
23390 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f a type conversio
233a0 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 n occurs as.** d
233b0 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 escribed above,
233c0 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 or until [sqlite
233d0 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 3_step()] or [sq
233e0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f lite3_reset()] o
233f0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 r.** [sqlite3_fi
23400 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c nalize()] is cal
23410 6c 65 64 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 led. The memory
23420 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 space used to h
23430 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 old strings.** a
23440 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 nd BLOBs is free
23450 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e d automatically.
23460 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 Do <b>not</b>
23470 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 pass the pointer
23480 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 s returned.** [s
23490 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
234a0 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f ob()], [sqlite3_
234b0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 column_text()],
234c0 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 etc. into.** [sq
234d0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a lite3_free()]..*
234e0 2a 0a 2a 2a 20 49 66 20 61 20 6d 65 6d 6f 72 79 *.** If a memory
234f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f allocation erro
23500 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 r occurs during
23510 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f the evaluation o
23520 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 f any.** of thes
23530 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 e routines, a de
23540 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 fault value is r
23550 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 eturned. The de
23560 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 fault value.** i
23570 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 s either the int
23580 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 eger 0, the floa
23590 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 ting point numbe
235a0 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c r 0.0, or a NULL
235b0 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 .** pointer. Su
235c0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 bsequent calls t
235d0 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f o [sqlite3_errco
235e0 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 de()] will retur
235f0 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d n.** [SQLITE_NOM
23600 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 EM]..**.** Requi
23610 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 rements:.** [H13
23620 38 30 33 5d 20 5b 48 31 33 38 30 36 5d 20 5b 48 803] [H13806] [H
23630 31 33 38 30 39 5d 20 5b 48 31 33 38 31 32 5d 20 13809] [H13812]
23640 5b 48 31 33 38 31 35 5d 20 5b 48 31 33 38 31 38 [H13815] [H13818
23650 5d 20 5b 48 31 33 38 32 31 5d 20 5b 48 31 33 38 ] [H13821] [H138
23660 32 34 5d 0a 2a 2a 20 5b 48 31 33 38 32 37 5d 20 24].** [H13827]
23670 5b 48 31 33 38 33 30 5d 0a 2a 2f 0a 53 51 4c 49 [H13830].*/.SQLI
23680 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 TE_API const voi
23690 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
236a0 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 n_blob(sqlite3_s
236b0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
236c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
236d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
236e0 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d ytes(sqlite3_stm
236f0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 t*, int iCol);.S
23700 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
23710 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
23720 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d es16(sqlite3_stm
23730 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 t*, int iCol);.S
23740 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 QLITE_API double
23750 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
23760 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 double(sqlite3_s
23770 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
23780 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
23790 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 sqlite3_column_i
237a0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a nt(sqlite3_stmt*
237b0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c , int iCol);.SQL
237c0 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f ITE_API sqlite3_
237d0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f int64 sqlite3_co
237e0 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 lumn_int64(sqlit
237f0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
23800 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 ol);.SQLITE_API
23810 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 const unsigned c
23820 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c har *sqlite3_col
23830 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 umn_text(sqlite3
23840 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
23850 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
23860 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
23870 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
23880 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
23890 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 nt iCol);.SQLITE
238a0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
238b0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c _column_type(sql
238c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
238d0 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 iCol);.SQLITE_AP
238e0 49 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 I sqlite3_value
238f0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
23900 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 value(sqlite3_st
23910 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
23920 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
23930 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 Destroy A Prepa
23940 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 red Statement Ob
23950 6a 65 63 74 20 7b 48 31 33 33 30 30 7d 20 3c 53 ject {H13300} <S
23960 37 30 33 30 30 3e 3c 53 33 30 31 30 30 3e 0a 2a 70300><S30100>.*
23970 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
23980 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 _finalize() func
23990 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 tion is called t
239a0 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 o delete a [prep
239b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
239c0 0a 2a 2a 20 49 66 20 74 68 65 20 73 74 61 74 65 .** If the state
239d0 6d 65 6e 74 20 77 61 73 20 65 78 65 63 75 74 65 ment was execute
239e0 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 6f d successfully o
239f0 72 20 6e 6f 74 20 65 78 65 63 75 74 65 64 20 61 r not executed a
23a00 74 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53 t all, then.** S
23a10 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 QLITE_OK is retu
23a20 72 6e 65 64 2e 20 49 66 20 65 78 65 63 75 74 69 rned. If executi
23a30 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d on of the statem
23a40 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65 6e 20 ent failed then
23a50 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 an.** [error cod
23a60 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 e] or [extended
23a70 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 error code] is r
23a80 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 eturned..**.** T
23a90 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 his routine can
23aa0 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 be called at any
23ab0 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 74 68 point during th
23ac0 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 e execution of t
23ad0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 he.** [prepared
23ae0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 66 20 statement]. If
23af0 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68 the virtual mach
23b00 69 6e 65 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 63 ine has not.** c
23b10 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 ompleted executi
23b20 6f 6e 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75 on when this rou
23b30 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 tine is called,
23b40 74 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 that is like.**
23b50 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 encountering an
23b60 65 72 72 6f 72 20 6f 72 20 61 6e 20 5b 73 71 6c error or an [sql
23b70 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c ite3_interrupt |
23b80 20 69 6e 74 65 72 72 75 70 74 5d 2e 0a 2a 2a 20 interrupt]..**
23b90 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61 74 Incomplete updat
23ba0 65 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64 es may be rolled
23bb0 20 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73 61 back and transa
23bc0 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c 65 64 2c ctions canceled,
23bd0 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e .** depending on
23be0 20 74 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63 the circumstanc
23bf0 65 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b es, and the.** [
23c00 65 72 72 6f 72 20 63 6f 64 65 5d 20 72 65 74 75 error code] retu
23c10 72 6e 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 rned will be [SQ
23c20 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a LITE_ABORT]..**.
23c30 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
23c40 0a 2a 2a 20 5b 48 31 31 33 30 32 5d 20 5b 48 31 .** [H11302] [H1
23c50 31 33 30 34 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 1304].*/.SQLITE_
23c60 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
23c70 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 finalize(sqlite3
23c80 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a _stmt *pStmt);..
23c90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
23ca0 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 Reset A Prepared
23cb0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 Statement Objec
23cc0 74 20 7b 48 31 33 33 33 30 7d 20 3c 53 37 30 33 t {H13330} <S703
23cd0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 00>.**.** The sq
23ce0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 lite3_reset() fu
23cf0 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 nction is called
23d00 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 to reset a [pre
23d10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
23d20 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 .** object back
23d30 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 to its initial s
23d40 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 tate, ready to b
23d50 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a e re-executed..*
23d60 2a 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d * Any SQL statem
23d70 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 ent variables th
23d80 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f at had values bo
23d90 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e und to them usin
23da0 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 g.** the [sqlite
23db0 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 3_bind_blob | sq
23dc0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 lite3_bind_*() A
23dd0 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 PI] retain their
23de0 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 values..** Use
23df0 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 [sqlite3_clear_b
23e00 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 indings()] to re
23e10 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 set the bindings
23e20 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 32 7d ..**.** {H11332}
23e30 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 The [sqlite3_re
23e40 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 set(S)] interfac
23e50 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 e resets the [pr
23e60 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
23e70 5d 20 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ] S.**
23e80 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 back to the begi
23e90 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f nning of its pro
23ea0 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 gram..**.** {H11
23eb0 33 33 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 334} If the most
23ec0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 recent call to
23ed0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 [sqlite3_step(S)
23ee0 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 ] for the.**
23ef0 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 [prepared
23f00 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 statement] S ret
23f10 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f urned [SQLITE_RO
23f20 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f W] or [SQLITE_DO
23f30 4e 45 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 NE],.**
23f40 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f or if [sqlite3_
23f50 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 step(S)] has nev
23f60 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 er before been c
23f70 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 20 alled on S,.**
23f80 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 then [sq
23f90 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 lite3_reset(S)]
23fa0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
23fb0 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 OK]..**.** {H113
23fc0 33 36 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 36} If the most
23fd0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b recent call to [
23fe0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d sqlite3_step(S)]
23ff0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 for the.**
24000 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 [prepared s
24010 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 tatement] S indi
24020 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 cated an error,
24030 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 then.**
24040 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
24050 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 S)] returns an a
24060 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f ppropriate [erro
24070 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b r code]..**.** {
24080 48 31 31 33 33 38 7d 20 54 68 65 20 5b 73 71 6c H11338} The [sql
24090 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 ite3_reset(S)] i
240a0 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f nterface does no
240b0 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c t change the val
240c0 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ues.**
240d0 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f of any [sqlite3_
240e0 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e bind_blob|bindin
240f0 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 gs] on the [prep
24100 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
24110 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 S..*/.SQLITE_API
24120 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 int sqlite3_res
24130 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 et(sqlite3_stmt
24140 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *pStmt);../*.**
24150 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 CAPI3REF: Create
24160 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c Or Redefine SQL
24170 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 31 Functions {H161
24180 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 00} <S20200>.**
24190 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 KEYWORDS: {funct
241a0 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 ion creation rou
241b0 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 tines}.** KEYWOR
241c0 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e DS: {application
241d0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
241e0 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 ction}.** KEYWOR
241f0 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e DS: {application
24200 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
24210 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 ctions}.**.** Th
24220 65 73 65 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e ese two function
24230 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 s (collectively
24240 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 known as "functi
24250 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 on creation rout
24260 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 ines").** are us
24270 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 ed to add SQL fu
24280 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 nctions or aggre
24290 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 gates or to rede
242a0 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f fine the behavio
242b0 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 r.** of existing
242c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f SQL functions o
242d0 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 r aggregates. T
242e0 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e he only differen
242f0 63 65 20 62 65 74 77 65 65 6e 20 74 68 65 0a 2a ce between the.*
24300 2a 20 74 77 6f 20 69 73 20 74 68 61 74 20 74 68 * two is that th
24310 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
24320 65 72 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 er, the name of
24330 74 68 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e the (scalar) fun
24340 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 ction or.** aggr
24350 65 67 61 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 egate, is encode
24360 64 20 69 6e 20 55 54 46 2d 38 20 66 6f 72 20 73 d in UTF-8 for s
24370 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
24380 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 nction() and UTF
24390 2d 31 36 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 -16.** for sqlit
243a0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
243b0 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 on16()..**.** Th
243c0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
243d0 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 r is the [databa
243e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 se connection] t
243f0 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a o which the SQL.
24400 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 ** function is t
24410 6f 20 62 65 20 61 64 64 65 64 2e 20 20 49 66 20 o be added. If
24420 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 61 6d a single program
24430 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 uses more than
24440 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 one database.**
24450 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 6e 74 65 72 connection inter
24460 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c 20 nally, then SQL
24470 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 functions must b
24480 65 20 61 64 64 65 64 20 69 6e 64 69 76 69 64 75 e added individu
24490 61 6c 6c 79 20 74 6f 0a 2a 2a 20 65 61 63 68 20 ally to.** each
244a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
244b0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ion..**.** The s
244c0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
244d0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 is the name of t
244e0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 he SQL function
244f0 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 to be created or
24500 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 .** redefined.
24510 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 The length of th
24520 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 e name is limite
24530 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20 d to 255 bytes,
24540 65 78 63 6c 75 73 69 76 65 20 6f 66 0a 2a 2a 20 exclusive of.**
24550 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 the zero-termina
24560 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 tor. Note that
24570 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 the name length
24580 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65 limit is in byte
24590 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 s, not.** charac
245a0 74 65 72 73 2e 20 20 41 6e 79 20 61 74 74 65 6d ters. Any attem
245b0 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 pt to create a f
245c0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c unction with a l
245d0 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 onger name.** wi
245e0 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 ll result in [SQ
245f0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 62 65 69 6e LITE_ERROR] bein
24600 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a g returned..**.*
24610 2a 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 * The third para
24620 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 meter (nArg).**
24630 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 is the number of
24640 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 arguments that
24650 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
24660 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 or.** aggregate
24670 20 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20 takes. If this
24680 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c parameter is -1,
24690 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 then the SQL fu
246a0 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 nction or.** agg
246b0 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 regate may take
246c0 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 any number of ar
246d0 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 guments between
246e0 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 0 and the limit.
246f0 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 ** set by [sqlit
24700 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 e3_limit]([SQLIT
24710 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e E_LIMIT_FUNCTION
24720 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 _ARG]). If the
24730 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 third.** paramet
24740 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 er is less than
24750 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 -1 or greater th
24760 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 an 127 then the
24770 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 behavior is.** u
24780 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
24790 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d The fourth param
247a0 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 eter, eTextRep,
247b0 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a specifies what.*
247c0 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c * [SQLITE_UTF8 |
247d0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 text encoding]
247e0 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f this SQL functio
247f0 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a n prefers for.**
24800 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e its parameters.
24810 20 20 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 Any SQL functi
24820 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f on implementatio
24830 6e 20 73 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 n should be able
24840 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b to work.** work
24850 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 with UTF-8, UTF
24860 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 -16le, or UTF-16
24870 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d be. But some im
24880 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 plementations ma
24890 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 y be.** more eff
248a0 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 icient with one
248b0 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e encoding than an
248c0 6f 74 68 65 72 2e 20 20 41 6e 20 61 70 70 6c 69 other. An appli
248d0 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e cation may.** in
248e0 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 voke sqlite3_cre
248f0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f ate_function() o
24900 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 r sqlite3_create
24910 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 _function16() mu
24920 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 ltiple.** times
24930 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 with the same fu
24940 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 nction but with
24950 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 different values
24960 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a of eTextRep..**
24970 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 When multiple i
24980 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f mplementations o
24990 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 f the same funct
249a0 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c ion are availabl
249b0 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c e, SQLite.** wil
249c0 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 l pick the one t
249d0 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 hat involves the
249e0 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 least amount of
249f0 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e data conversion
24a00 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 ..** If there is
24a10 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 only a single i
24a20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 mplementation wh
24a30 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 ich does not car
24a40 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 e what text.** e
24a50 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c ncoding is used,
24a60 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 then the fourth
24a70 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 argument should
24a80 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d be [SQLITE_ANY]
24a90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 ..**.** The fift
24aa0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 h parameter is a
24ab0 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e n arbitrary poin
24ac0 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d ter. The implem
24ad0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a entation of the.
24ae0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 ** function can
24af0 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 gain access to t
24b00 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e his pointer usin
24b10 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f g [sqlite3_user_
24b20 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 data()]..**.** T
24b30 68 65 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68 he seventh, eigh
24b40 74 68 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 th and ninth par
24b50 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 ameters, xFunc,
24b60 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c xStep and xFinal
24b70 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 , are.** pointer
24b80 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 s to C-language
24b90 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 functions that i
24ba0 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c mplement the SQL
24bb0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 function or.**
24bc0 61 67 67 72 65 67 61 74 65 2e 20 41 20 73 63 61 aggregate. A sca
24bd0 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e lar SQL function
24be0 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 requires an imp
24bf0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 lementation of t
24c00 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c he xFunc.** call
24c10 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 back only, NULL
24c20 70 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 pointers should
24c30 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 be passed as the
24c40 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 xStep and xFina
24c50 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e l.** parameters.
24c60 20 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 An aggregate SQ
24c70 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 L function requi
24c80 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 res an implement
24c90 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a ation of xStep.*
24ca0 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 * and xFinal and
24cb0 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 NULL should be
24cc0 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 passed for xFunc
24cd0 2e 20 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 . To delete an e
24ce0 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 xisting.** SQL f
24cf0 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 unction or aggre
24d00 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 gate, pass NULL
24d10 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 for all three fu
24d20 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 nction callbacks
24d30 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65 ..**.** It is pe
24d40 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 rmitted to regis
24d50 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 ter multiple imp
24d60 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 lementations of
24d70 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 the same.** func
24d80 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 tions with the s
24d90 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 ame name but wit
24da0 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 h either differi
24db0 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a ng numbers of.**
24dc0 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 arguments or di
24dd0 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 ffering preferre
24de0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 d text encodings
24df0 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 . SQLite will u
24e00 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d se.** the implem
24e10 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f entation that mo
24e20 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 st closely match
24e30 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 es the way in wh
24e40 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 ich the.** SQL f
24e50 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e unction is used.
24e60 20 20 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 A function imp
24e70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 lementation with
24e80 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a a non-negative.
24e90 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 ** nArg paramete
24ea0 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 r is a better ma
24eb0 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 tch than a funct
24ec0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ion implementati
24ed0 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 on with.** a neg
24ee0 61 74 69 76 65 20 6e 41 72 67 2e 20 20 41 20 66 ative nArg. A f
24ef0 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 unction where th
24f00 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 e preferred text
24f10 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 encoding.** mat
24f20 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 ches the databas
24f30 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 e encoding is a
24f40 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 better.** match
24f50 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 than a function
24f60 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 where the encodi
24f70 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e ng is different.
24f80 20 20 0a 2a 2a 20 41 20 66 75 6e 63 74 69 6f 6e .** A function
24f90 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 where the encod
24fa0 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 ing difference i
24fb0 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c s between UTF16l
24fc0 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a e and UTF16be.**
24fd0 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 is a closer mat
24fe0 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 ch than a functi
24ff0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 on where the enc
25000 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 oding difference
25010 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 is.** between U
25020 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a TF8 and UTF16..*
25030 2a 0a 2a 2a 20 42 75 69 6c 74 2d 69 6e 20 66 75 *.** Built-in fu
25040 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f nctions may be o
25050 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 verloaded by new
25060 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
25070 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a ined functions..
25080 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 70 70 ** The first app
25090 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
250a0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 function with a
250b0 20 67 69 76 65 6e 20 6e 61 6d 65 20 6f 76 65 72 given name over
250c0 72 69 64 65 73 20 61 6c 6c 0a 2a 2a 20 62 75 69 rides all.** bui
250d0 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 lt-in functions
250e0 69 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 in the same [dat
250f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
25100 5d 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 ] with the same
25110 6e 61 6d 65 2e 0a 2a 2a 20 53 75 62 73 65 71 75 name..** Subsequ
25120 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d ent application-
25130 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
25140 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 6e 61 s of the same na
25150 6d 65 20 6f 6e 6c 79 20 6f 76 65 72 72 69 64 65 me only override
25160 20 0a 2a 2a 20 70 72 69 6f 72 20 61 70 70 6c 69 .** prior appli
25170 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
25180 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 61 72 unctions that ar
25190 65 20 61 6e 20 65 78 61 63 74 20 6d 61 74 63 68 e an exact match
251a0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 for the.** numb
251b0 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 er of parameters
251c0 20 61 6e 64 20 70 72 65 66 65 72 72 65 64 20 65 and preferred e
251d0 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 41 ncoding..**.** A
251e0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 n application-de
251f0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 fined function i
25200 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 s permitted to c
25210 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c all other.** SQL
25220 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 ite interfaces.
25230 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 However, such c
25240 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a alls must not.**
25250 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 close the datab
25260 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e ase connection n
25270 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 or finalize or r
25280 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 eset the prepare
25290 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 d.** statement i
252a0 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 n which the func
252b0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e tion is running.
252c0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
252d0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 31 30 33 5d nts:.** [H16103]
252e0 20 5b 48 31 36 31 30 36 5d 20 5b 48 31 36 31 30 [H16106] [H1610
252f0 39 5d 20 5b 48 31 36 31 31 32 5d 20 5b 48 31 36 9] [H16112] [H16
25300 31 31 38 5d 20 5b 48 31 36 31 32 31 5d 20 5b 48 118] [H16121] [H
25310 31 36 31 32 37 5d 0a 2a 2a 20 5b 48 31 36 31 33 16127].** [H1613
25320 30 5d 20 5b 48 31 36 31 33 33 5d 20 5b 48 31 36 0] [H16133] [H16
25330 31 33 36 5d 20 5b 48 31 36 31 33 39 5d 20 5b 48 136] [H16139] [H
25340 31 36 31 34 32 5d 0a 2a 2f 0a 53 51 4c 49 54 45 16142].*/.SQLITE
25350 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
25360 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
25370 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
25380 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
25390 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 FunctionName,.
253a0 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 int nArg,. int
253b0 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 eTextRep,. void
253c0 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 *pApp,. void (
253d0 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f *xFunc)(sqlite3_
253e0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c context*,int,sql
253f0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 ite3_value**),.
25400 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 void (*xStep)(s
25410 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
25420 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 int,sqlite3_valu
25430 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 e**),. void (*x
25440 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 Final)(sqlite3_c
25450 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 ontext*).);.SQLI
25460 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
25470 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
25480 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 on16(. sqlite3
25490 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 *db,. const voi
254a0 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 d *zFunctionName
254b0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 ,. int nArg,.
254c0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 int eTextRep,.
254d0 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f void *pApp,. vo
254e0 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 id (*xFunc)(sqli
254f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 te3_context*,int
25500 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a ,sqlite3_value**
25510 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 ),. void (*xSte
25520 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 p)(sqlite3_conte
25530 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f xt*,int,sqlite3_
25540 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 value**),. void
25550 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 (*xFinal)(sqlit
25560 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a e3_context*).);.
25570 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
25580 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 20 Text Encodings
25590 7b 48 31 30 32 36 37 7d 20 3c 53 35 30 32 30 30 {H10267} <S50200
255a0 3e 20 3c 48 31 36 31 30 30 3e 0a 2a 2a 0a 2a 2a > <H16100>.**.**
255b0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 These constant
255c0 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 define integer c
255d0 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73 odes that repres
255e0 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a ent the various.
255f0 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 ** text encoding
25600 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 s supported by S
25610 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e QLite..*/.#defin
25620 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 e SQLITE_UTF8
25630 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 1.#defin
25640 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 e SQLITE_UTF16LE
25650 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 2.#defin
25660 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 e SQLITE_UTF16BE
25670 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 3.#defin
25680 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 e SQLITE_UTF16
25690 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 4 /*
256a0 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 Use native byte
256b0 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 order */.#define
256c0 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 SQLITE_ANY
256d0 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 5 /* s
256e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
256f0 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 nction only */.#
25700 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 define SQLITE_UT
25710 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 F16_ALIGNED 8
25720 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 /* sqlite3_cre
25730 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e ate_collation on
25740 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ly */../*.** CAP
25750 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 I3REF: Deprecate
25760 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 d Functions.** D
25770 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 EPRECATED.**.**
25780 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 These functions
25790 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d are [deprecated]
257a0 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d . In order to m
257b0 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 aintain.** backw
257c0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 ards compatibili
257d0 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f ty with older co
257e0 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 de, these functi
257f0 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a ons continue .**
25800 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 to be supported
25810 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 . However, new
25820 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f applications sho
25830 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 uld avoid.** the
25840 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 use of these fu
25850 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c nctions. To hel
25860 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 p encourage peop
25870 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 le to avoid.** u
25880 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 sing these funct
25890 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 ions, we are not
258a0 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 going to tell y
258b0 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e ou what they do.
258c0 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 .*/.#ifndef SQLI
258d0 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 TE_OMIT_DEPRECAT
258e0 45 44 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 ED.SQLITE_API SQ
258f0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 LITE_DEPRECATED
25900 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 int sqlite3_aggr
25910 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 egate_count(sqli
25920 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 te3_context*);.S
25930 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
25940 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 _DEPRECATED int
25950 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 sqlite3_expired(
25960 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a sqlite3_stmt*);.
25970 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
25980 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 E_DEPRECATED int
25990 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 sqlite3_transfe
259a0 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 r_bindings(sqlit
259b0 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 e3_stmt*, sqlite
259c0 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 3_stmt*);.SQLITE
259d0 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 _API SQLITE_DEPR
259e0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 ECATED int sqlit
259f0 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 e3_global_recove
25a00 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f r(void);.SQLITE_
25a10 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 API SQLITE_DEPRE
25a20 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 CATED void sqlit
25a30 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 e3_thread_cleanu
25a40 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f p(void);.SQLITE_
25a50 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 API SQLITE_DEPRE
25a60 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 CATED int sqlite
25a70 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 3_memory_alarm(v
25a80 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c oid(*)(void*,sql
25a90 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c ite3_int64,int),
25aa0 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e void*,sqlite3_in
25ab0 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a t64);.#endif../*
25ac0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 .** CAPI3REF: Ob
25ad0 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 taining SQL Func
25ae0 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 tion Parameter V
25af0 61 6c 75 65 73 20 7b 48 31 35 31 30 30 7d 20 3c alues {H15100} <
25b00 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S20200>.**.** Th
25b10 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 e C-language imp
25b20 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 lementation of S
25b30 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 QL functions and
25b40 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 aggregates uses
25b50 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 .** this set of
25b60 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e interface routin
25b70 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 es to access the
25b80 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 parameter value
25b90 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 s on.** the func
25ba0 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 tion or aggregat
25bb0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 e..**.** The xFu
25bc0 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 nc (for scalar f
25bd0 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 unctions) or xSt
25be0 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 ep (for aggregat
25bf0 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a es) parameters.*
25c00 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 * to [sqlite3_cr
25c10 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d eate_function()]
25c20 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 and [sqlite3_cr
25c30 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 eate_function16(
25c40 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c )].** define cal
25c50 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c lbacks that impl
25c60 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 ement the SQL fu
25c70 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 nctions and aggr
25c80 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 egates..** The 4
25c90 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
25ca0 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 these callbacks
25cb0 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 is an array of p
25cc0 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 ointers to.** [p
25cd0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
25ce0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e _value] objects.
25cf0 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b There is one [
25d00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
25d10 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 bject for.** eac
25d20 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
25d30 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e he SQL function.
25d40 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 These routines
25d50 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 are used to.**
25d60 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 extract values f
25d70 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 rom the [sqlite3
25d80 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e _value] objects.
25d90 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
25da0 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 tines work only
25db0 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 with [protected
25dc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
25dd0 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 bjects..** Any a
25de0 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 ttempt to use th
25df0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 ese routines on
25e00 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 an [unprotected
25e10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a sqlite3_value].*
25e20 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 * object results
25e30 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 in undefined be
25e40 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 havior..**.** Th
25e50 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 ese routines wor
25e60 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 k just like the
25e70 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 corresponding [c
25e80 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e olumn access fun
25e90 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 ctions].** excep
25ea0 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f t that these ro
25eb0 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 utines take a si
25ec0 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 ngle [protected
25ed0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
25ee0 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 bject.** pointer
25ef0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 instead of a [s
25f00 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f qlite3_stmt*] po
25f10 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 inter and an int
25f20 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 eger column numb
25f30 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 er..**.** The sq
25f40 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
25f50 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 16() interface e
25f60 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 xtracts a UTF-16
25f70 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 string.** in th
25f80 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 e native byte-or
25f90 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 der of the host
25fa0 6d 61 63 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a machine. The.**
25fb0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
25fc0 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 ext16be() and sq
25fd0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
25fe0 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 16le() interface
25ff0 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 s.** extract UTF
26000 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 -16 strings as b
26010 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 ig-endian and li
26020 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 ttle-endian resp
26030 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 ectively..**.**
26040 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 The sqlite3_valu
26050 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 e_numeric_type()
26060 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d interface attem
26070 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 pts to apply.**
26080 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 numeric affinity
26090 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 to the value.
260a0 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 This means that
260b0 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a an attempt is.**
260c0 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 made to convert
260d0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e the value to an
260e0 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 integer or floa
260f0 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a ting point. If.
26100 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 ** such a conver
26110 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 sion is possible
26120 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 without loss of
26130 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e information (in
26140 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c other.** words,
26150 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 if the value is
26160 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c a string that l
26170 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 ooks like a numb
26180 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 er).** then the
26190 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 conversion is pe
261a0 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 rformed. Otherw
261b0 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f ise no conversio
261c0 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 n occurs..** The
261d0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 [SQLITE_INTEGER
261e0 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 | datatype] aft
261f0 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 er conversion is
26200 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
26210 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 Please pay part
26220 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e icular attention
26230 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 to the fact tha
26240 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 t the pointer re
26250 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b turned.** from [
26260 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c sqlite3_value_bl
26270 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f ob()], [sqlite3_
26280 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f value_text()], o
26290 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 r.** [sqlite3_va
262a0 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 lue_text16()] ca
262b0 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 n be invalidated
262c0 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 by a subsequent
262d0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c call to.** [sql
262e0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 ite3_value_bytes
262f0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 ()], [sqlite3_va
26300 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 lue_bytes16()],
26310 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 [sqlite3_value_t
26320 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 ext()],.** or [s
26330 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
26340 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 t16()]..**.** Th
26350 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 ese routines mus
26360 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d t be called from
26370 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 the same thread
26380 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 as.** the SQL f
26390 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 unction that sup
263a0 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 plied the [sqlit
263b0 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d e3_value*] param
263c0 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 eters..**.** Req
263d0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
263e0 31 35 31 30 33 5d 20 5b 48 31 35 31 30 36 5d 20 15103] [H15106]
263f0 5b 48 31 35 31 30 39 5d 20 5b 48 31 35 31 31 32 [H15109] [H15112
26400 5d 20 5b 48 31 35 31 31 35 5d 20 5b 48 31 35 31 ] [H15115] [H151
26410 31 38 5d 20 5b 48 31 35 31 32 31 5d 20 5b 48 31 18] [H15121] [H1
26420 35 31 32 34 5d 0a 2a 2a 20 5b 48 31 35 31 32 37 5124].** [H15127
26430 5d 20 5b 48 31 35 31 33 30 5d 20 5b 48 31 35 31 ] [H15130] [H151
26440 33 33 5d 20 5b 48 31 35 31 33 36 5d 0a 2a 2f 0a 33] [H15136].*/.
26450 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
26460 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 void *sqlite3_v
26470 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 alue_blob(sqlite
26480 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 3_value*);.SQLIT
26490 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
264a0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 3_value_bytes(sq
264b0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 lite3_value*);.S
264c0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
264d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 lite3_value_byte
264e0 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 s16(sqlite3_valu
264f0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 e*);.SQLITE_API
26500 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 double sqlite3_v
26510 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 alue_double(sqli
26520 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c te3_value*);.SQL
26530 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
26540 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 te3_value_int(sq
26550 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 lite3_value*);.S
26560 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 QLITE_API sqlite
26570 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 3_int64 sqlite3_
26580 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 value_int64(sqli
26590 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c te3_value*);.SQL
265a0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e ITE_API const un
265b0 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c signed char *sql
265c0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 ite3_value_text(
265d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
265e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
265f0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
26600 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c value_text16(sql
26610 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 ite3_value*);.SQ
26620 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 LITE_API const v
26630 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c oid *sqlite3_val
26640 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 ue_text16le(sqli
26650 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c te3_value*);.SQL
26660 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f ITE_API const vo
26670 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 id *sqlite3_valu
26680 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 e_text16be(sqlit
26690 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 e3_value*);.SQLI
266a0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
266b0 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 e3_value_type(sq
266c0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 lite3_value*);.S
266d0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
266e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 lite3_value_nume
266f0 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 ric_type(sqlite3
26700 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a _value*);../*.**
26710 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 CAPI3REF: Obtai
26720 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 n Aggregate Func
26730 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 7b 48 31 tion Context {H1
26740 36 32 31 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 6210} <S20200>.*
26750 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 *.** The impleme
26760 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67 67 72 65 ntation of aggre
26770 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f gate SQL functio
26780 6e 73 20 75 73 65 20 74 68 69 73 20 72 6f 75 74 ns use this rout
26790 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a ine to allocate.
267a0 2a 2a 20 61 20 73 74 72 75 63 74 75 72 65 20 66 ** a structure f
267b0 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 or storing their
267c0 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 state..**.** Th
267d0 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 e first time the
267e0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 sqlite3_aggrega
267f0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 72 6f 75 te_context() rou
26800 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 66 tine is called f
26810 6f 72 20 61 0a 2a 2a 20 70 61 72 74 69 63 75 6c or a.** particul
26820 61 72 20 61 67 67 72 65 67 61 74 65 2c 20 53 51 ar aggregate, SQ
26830 4c 69 74 65 20 61 6c 6c 6f 63 61 74 65 73 20 6e Lite allocates n
26840 42 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c Bytes of memory,
26850 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 zeroes out that
26860 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 .** memory, and
26870 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
26880 72 20 74 6f 20 69 74 2e 20 4f 6e 20 73 65 63 6f r to it. On seco
26890 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e nd and subsequen
268a0 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 t calls to.** sq
268b0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
268c0 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 context() for th
268d0 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 e same aggregate
268e0 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64 65 78 2c function index,
268f0 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 .** the same buf
26900 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e fer is returned.
26910 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 The implementat
26920 69 6f 6e 20 6f 66 20 74 68 65 20 61 67 67 72 65 ion of the aggre
26930 67 61 74 65 20 63 61 6e 20 75 73 65 0a 2a 2a 20 gate can use.**
26940 74 68 65 20 72 65 74 75 72 6e 65 64 20 62 75 66 the returned buf
26950 66 65 72 20 74 6f 20 61 63 63 75 6d 75 6c 61 74 fer to accumulat
26960 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 e data..**.** SQ
26970 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c Lite automatical
26980 6c 79 20 66 72 65 65 73 20 74 68 65 20 61 6c 6c ly frees the all
26990 6f 63 61 74 65 64 20 62 75 66 66 65 72 20 77 68 ocated buffer wh
269a0 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 en the aggregate
269b0 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 .** query conclu
269c0 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 des..**.** The f
269d0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 73 irst parameter s
269e0 68 6f 75 6c 64 20 62 65 20 61 20 63 6f 70 79 20 hould be a copy
269f0 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 of the.** [sqlit
26a00 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c e3_context | SQL
26a10 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 function contex
26a20 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 t] that is the f
26a30 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a irst parameter.*
26a40 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 * to the callbac
26a50 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 k routine that i
26a60 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 mplements the ag
26a70 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e gregate function
26a80 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 ..**.** This rou
26a90 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c tine must be cal
26aa0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d led from the sam
26ab0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 e thread in whic
26ac0 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 h.** the aggrega
26ad0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 te SQL function
26ae0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a is running..**.*
26af0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
26b00 2a 2a 20 5b 48 31 36 32 31 31 5d 20 5b 48 31 36 ** [H16211] [H16
26b10 32 31 33 5d 20 5b 48 31 36 32 31 35 5d 20 5b 48 213] [H16215] [H
26b20 31 36 32 31 37 5d 0a 2a 2f 0a 53 51 4c 49 54 45 16217].*/.SQLITE
26b30 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 _API void *sqlit
26b40 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
26b50 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e text(sqlite3_con
26b60 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 text*, int nByte
26b70 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 s);../*.** CAPI3
26b80 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 REF: User Data F
26b90 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 or Functions {H1
26ba0 36 32 34 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 6240} <S20200>.*
26bb0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
26bc0 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 _user_data() int
26bd0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 erface returns a
26be0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 copy of.** the
26bf0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 pointer that was
26c00 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70 the pUserData p
26c10 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 arameter (the 5t
26c20 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 h parameter).**
26c30 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
26c40 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
26c50 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 )].** and [sqlit
26c60 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
26c70 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 on16()] routines
26c80 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 that originally
26c90 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 .** registered t
26ca0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 he application d
26cb0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e efined function.
26cc0 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 {END}.**.** Thi
26cd0 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 s routine must b
26ce0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 e called from th
26cf0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e e same thread in
26d00 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 which.** the ap
26d10 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
26d20 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 d function is ru
26d30 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 nning..**.** Req
26d40 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
26d50 31 36 32 34 33 5d 0a 2a 2f 0a 53 51 4c 49 54 45 16243].*/.SQLITE
26d60 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 _API void *sqlit
26d70 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c e3_user_data(sql
26d80 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a ite3_context*);.
26d90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
26da0 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 Database Connec
26db0 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f tion For Functio
26dc0 6e 73 20 7b 48 31 36 32 35 30 7d 20 3c 53 36 30 ns {H16250} <S60
26dd0 36 30 30 3e 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 600><S20200>.**.
26de0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 ** The sqlite3_c
26df0 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 ontext_db_handle
26e00 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 () interface ret
26e10 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a urns a copy of.*
26e20 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f * the pointer to
26e30 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
26e40 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 onnection] (the
26e50 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 1st parameter).*
26e60 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 * of the [sqlite
26e70 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
26e80 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c n()].** and [sql
26e90 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
26ea0 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e tion16()] routin
26eb0 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c es that original
26ec0 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 ly.** registered
26ed0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
26ee0 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f defined functio
26ef0 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 n..**.** Require
26f00 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 32 35 ments:.** [H1625
26f10 33 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 3].*/.SQLITE_API
26f20 20 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 sqlite3 *sqlite
26f30 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 3_context_db_han
26f40 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 dle(sqlite3_cont
26f50 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ext*);../*.** CA
26f60 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e PI3REF: Function
26f70 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 20 Auxiliary Data
26f80 7b 48 31 36 32 37 30 7d 20 3c 53 32 30 32 30 30 {H16270} <S20200
26f90 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c >.**.** The foll
26fa0 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 owing two functi
26fb0 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 ons may be used
26fc0 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 by scalar SQL fu
26fd0 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 nctions to.** as
26fe0 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 sociate metadata
26ff0 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 with argument v
27000 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 alues. If the sa
27010 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 me value is pass
27020 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c ed to.** multipl
27030 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 e invocations of
27040 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 the same SQL fu
27050 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 nction during qu
27060 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 ery execution, u
27070 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 nder.** some cir
27080 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 cumstances the a
27090 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 ssociated metada
270a0 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 ta may be preser
270b0 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a ved. This may.**
270c0 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 be used, for ex
270d0 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 ample, to add a
270e0 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 regular-expressi
270f0 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c on matching scal
27100 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 ar.** function.
27110 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 The compiled ver
27120 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 sion of the regu
27130 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 lar expression i
27140 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d s stored as.** m
27150 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 etadata associat
27160 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 ed with the SQL
27170 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 value passed as
27180 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 the regular expr
27190 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 ession.** patter
271a0 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 n. The compiled
271b0 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 regular express
271c0 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 ion can be reuse
271d0 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a d on multiple.**
271e0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 invocations of
271f0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f the same functio
27200 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 n so that the or
27210 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 iginal pattern s
27220 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f tring.** does no
27230 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 t need to be rec
27240 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 ompiled on each
27250 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a invocation..**.*
27260 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 * The sqlite3_ge
27270 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 t_auxdata() inte
27280 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
27290 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d pointer to the m
272a0 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 etadata.** assoc
272b0 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c iated by the sql
272c0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 ite3_set_auxdata
272d0 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 () function with
272e0 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e the Nth argumen
272f0 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 t.** value to th
27300 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
27310 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 fined function.
27320 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 If no metadata h
27330 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 as been ever.**
27340 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 been set for the
27350 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 Nth argument of
27360 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f the function, o
27370 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 73 70 r if the corresp
27380 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 onding.** functi
27390 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 on parameter has
273a0 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74 changed since t
273b0 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73 he meta-data was
273c0 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 set,.** then sq
273d0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 lite3_get_auxdat
273e0 61 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 a() returns a NU
273f0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
27400 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 * The sqlite3_se
27410 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 t_auxdata() inte
27420 72 66 61 63 65 20 73 61 76 65 73 20 74 68 65 20 rface saves the
27430 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e metadata.** poin
27440 74 65 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 ted to by its 3r
27450 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 d parameter as t
27460 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 he metadata for
27470 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 the N-th.** argu
27480 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c ment of the appl
27490 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
274a0 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 function. Subse
274b0 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 quent.** calls t
274c0 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 o sqlite3_get_au
274d0 78 64 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 xdata() might re
274e0 74 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 turn this data,
274f0 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 if it has.** not
27500 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e been destroyed.
27510 0a 2a 2a 20 49 66 20 69 74 20 69 73 20 6e 6f 74 .** If it is not
27520 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 NULL, SQLite wi
27530 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 ll invoke the de
27540 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 structor.** func
27550 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 tion given by th
27560 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 4th parameter
27570 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 to sqlite3_set_a
27580 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 uxdata() on.** t
27590 68 65 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e he metadata when
275a0 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 the correspondi
275b0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 ng function para
275c0 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a meter changes.**
275d0 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c or when the SQL
275e0 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c statement compl
275f0 65 74 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 etes, whichever
27600 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a comes first..**.
27610 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 ** SQLite is fre
27620 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 e to call the de
27630 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f structor and dro
27640 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e p metadata on an
27650 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f y.** parameter o
27660 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 f any function a
27670 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 54 68 65 t any time. The
27680 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 only guarantee
27690 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 is that.** the d
276a0 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 estructor will b
276b0 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 e called before
276c0 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 the metadata is
276d0 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 dropped..**.** I
276e0 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 n practice, meta
276f0 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65 data is preserve
27700 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 d between functi
27710 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 on calls for.**
27720 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 expressions that
27730 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 are constant at
27740 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 compile time. T
27750 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 his includes lit
27760 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 eral.** values a
27770 6e 64 20 53 51 4c 20 76 61 72 69 61 62 6c 65 73 nd SQL variables
27780 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f ..**.** These ro
27790 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 utines must be c
277a0 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 alled from the s
277b0 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 ame thread in wh
277c0 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 ich.** the SQL f
277d0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 unction is runni
277e0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 ng..**.** Requir
277f0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 32 ements:.** [H162
27800 37 32 5d 20 5b 48 31 36 32 37 34 5d 20 5b 48 31 72] [H16274] [H1
27810 36 32 37 36 5d 20 5b 48 31 36 32 37 37 5d 20 5b 6276] [H16277] [
27820 48 31 36 32 37 38 5d 20 5b 48 31 36 32 37 39 5d H16278] [H16279]
27830 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 .*/.SQLITE_API v
27840 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 oid *sqlite3_get
27850 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 _auxdata(sqlite3
27860 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e _context*, int N
27870 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f );.SQLITE_API vo
27880 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 id sqlite3_set_a
27890 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 uxdata(sqlite3_c
278a0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 ontext*, int N,
278b0 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 void*, void (*)(
278c0 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a void*));.../*.**
278d0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 CAPI3REF: Const
278e0 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 ants Defining Sp
278f0 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 ecial Destructor
27900 20 42 65 68 61 76 69 6f 72 20 7b 48 31 30 32 38 Behavior {H1028
27910 30 7d 20 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 0} <S30100>.**.*
27920 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63 * These are spec
27930 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 ial values for t
27940 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 he destructor th
27950 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 at is passed in
27960 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 as the.** final
27970 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 argument to rout
27980 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 ines like [sqlit
27990 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 e3_result_blob()
279a0 5d 2e 20 20 49 66 20 74 68 65 20 64 65 73 74 72 ]. If the destr
279b0 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e uctor.** argumen
279c0 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 t is SQLITE_STAT
279d0 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 IC, it means tha
279e0 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f t the content po
279f0 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e inter is constan
27a00 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 t.** and will ne
27a10 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 ver change. It
27a20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f does not need to
27a30 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 be destroyed.
27a40 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 The.** SQLITE_TR
27a50 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 ANSIENT value me
27a60 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e ans that the con
27a70 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 tent will likely
27a80 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 change in.** th
27a90 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e e near future an
27aa0 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 d that SQLite sh
27ab0 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 ould make its ow
27ac0 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f n private copy o
27ad0 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 f.** the content
27ae0 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e before returnin
27af0 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 g..**.** The typ
27b00 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 edef is necessar
27b10 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 y to work around
27b20 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 problems in cer
27b30 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 tain.** C++ comp
27b40 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b ilers. See tick
27b50 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 et #2191..*/.typ
27b60 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 edef void (*sqli
27b70 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 te3_destructor_t
27b80 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 ype)(void*);.#de
27b90 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 fine SQLITE_STAT
27ba0 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 IC ((sqlite
27bb0 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 3_destructor_typ
27bc0 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c e)0).#define SQL
27bd0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 ITE_TRANSIENT
27be0 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 ((sqlite3_destru
27bf0 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f ctor_type)-1)../
27c00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
27c10 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c etting The Resul
27c20 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 t Of An SQL Func
27c30 74 69 6f 6e 20 7b 48 31 36 34 30 30 7d 20 3c 53 tion {H16400} <S
27c40 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20200>.**.** The
27c50 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
27c60 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e used by the xFun
27c70 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c c or xFinal call
27c80 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d backs that.** im
27c90 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 plement SQL func
27ca0 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 tions and aggreg
27cb0 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 ates. See.** [s
27cc0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
27cd0 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 nction()] and [s
27ce0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
27cf0 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 nction16()].** f
27d00 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e or additional in
27d10 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a formation..**.**
27d20 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 These functions
27d30 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 work very much
27d40 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 like the [parame
27d50 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d ter binding] fam
27d60 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 ily of.** functi
27d70 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 ons used to bind
27d80 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 values to host
27d90 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 parameters in pr
27da0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
27db0 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 s..** Refer to t
27dc0 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 he [SQL paramete
27dd0 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e r] documentation
27de0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 for additional
27df0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a information..**.
27e00 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 ** The sqlite3_r
27e10 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 esult_blob() int
27e20 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 erface sets the
27e30 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 result from.** a
27e40 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 n application-de
27e50 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 fined function t
27e60 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 o be the BLOB wh
27e70 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 ose content is p
27e80 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 ointed.** to by
27e90 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
27ea0 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 eter and which i
27eb0 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 s N bytes long w
27ec0 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a here N is the.**
27ed0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
27ee0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
27ef0 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 te3_result_zerob
27f00 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 lob() interfaces
27f10 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 set the result
27f20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 of.** the applic
27f30 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
27f40 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 nction to be a B
27f50 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 LOB containing a
27f60 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 ll zero.** bytes
27f70 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 and N bytes in
27f80 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 size, where N is
27f90 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 the value of th
27fa0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e e 2nd parameter.
27fb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
27fc0 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 e3_result_double
27fd0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 () interface set
27fe0 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f s the result fro
27ff0 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 m.** an applicat
28000 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
28010 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f tion to be a flo
28020 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 ating point valu
28030 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 e specified.** b
28040 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 y its 2nd argume
28050 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 nt..**.** The sq
28060 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
28070 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 or() and sqlite3
28080 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
28090 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 ) functions.** c
280a0 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 ause the impleme
280b0 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f nted SQL functio
280c0 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 n to throw an ex
280d0 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 53 51 4c 69 ception..** SQLi
280e0 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69 te uses the stri
280f0 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 ng pointed to by
28100 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 the.** 2nd para
28110 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 meter of sqlite3
28120 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 _result_error()
28130 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c or sqlite3_resul
28140 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 t_error16().** a
28150 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e s the text of an
28160 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 error message.
28170 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 SQLite interpre
28180 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 ts the error.**
28190 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 message string f
281a0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 rom sqlite3_resu
281b0 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 lt_error() as UT
281c0 46 2d 38 2e 20 53 51 4c 69 74 65 0a 2a 2a 20 69 F-8. SQLite.** i
281d0 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74 nterprets the st
281e0 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 ring from sqlite
281f0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 3_result_error16
28200 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 () as UTF-16 in
28210 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f native.** byte o
28220 72 64 65 72 2e 20 20 49 66 20 74 68 65 20 74 68 rder. If the th
28230 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ird parameter to
28240 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
28250 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 error().** or sq
28260 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
28270 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 or16() is negati
28280 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 ve then SQLite t
28290 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f akes as the erro
282a0 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c r.** message all
282b0 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 text up through
282c0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 the first zero
282d0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 character..** If
282e0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d the third param
282f0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
28300 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f result_error() o
28310 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 r.** sqlite3_res
28320 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 ult_error16() is
28330 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 non-negative th
28340 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 en SQLite takes
28350 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 that many.** byt
28360 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 es (not characte
28370 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 rs) from the 2nd
28380 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 parameter as th
28390 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e e error message.
283a0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
283b0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 result_error() a
283c0 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c nd sqlite3_resul
283d0 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 t_error16().** r
283e0 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 outines make a p
283f0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 rivate copy of t
28400 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 he error message
28410 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 text before.**
28420 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 they return. He
28430 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 nce, the calling
28440 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 function can de
28450 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d allocate or.** m
28460 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61 odify the text a
28470 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e fter they return
28480 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a without harm..*
28490 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 * The sqlite3_re
284a0 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 sult_error_code(
284b0 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 ) function chang
284c0 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 es the error cod
284d0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 e.** returned by
284e0 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 SQLite as a res
284f0 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 ult of an error
28500 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 in a function.
28510 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 By default,.** t
28520 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 he error code is
28530 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 SQLITE_ERROR.
28540 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c A subsequent cal
28550 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 l to sqlite3_res
28560 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f ult_error().** o
28570 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 r sqlite3_result
28580 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 _error16() reset
28590 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 s the error code
285a0 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 to SQLITE_ERROR
285b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
285c0 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 te3_result_toobi
285d0 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 g() interface ca
285e0 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 uses SQLite to t
285f0 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a hrow an error.**
28600 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 indicating that
28610 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f a string or BLO
28620 42 20 69 73 20 74 6f 20 6c 6f 6e 67 20 74 6f 20 B is to long to
28630 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a represent..**.**
28640 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 The sqlite3_res
28650 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 ult_nomem() inte
28660 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c rface causes SQL
28670 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 ite to throw an
28680 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 error.** indicat
28690 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 ing that a memor
286a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 y allocation fai
286b0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 led..**.** The s
286c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e qlite3_result_in
286d0 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 t() interface se
286e0 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 ts the return va
286f0 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 lue.** of the ap
28700 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
28710 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 d function to be
28720 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e the 32-bit sign
28730 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 ed integer.** va
28740 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 lue given in the
28750 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2nd argument..*
28760 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 * The sqlite3_re
28770 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 sult_int64() int
28780 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 erface sets the
28790 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 return value.**
287a0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 of the applicati
287b0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
287c0 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 ion to be the 64
287d0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 -bit signed inte
287e0 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 ger.** value giv
287f0 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 en in the 2nd ar
28800 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 gument..**.** Th
28810 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
28820 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 _null() interfac
28830 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 e sets the retur
28840 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 n value.** of th
28850 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
28860 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 fined function t
28870 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a o be NULL..**.**
28880 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 The sqlite3_res
28890 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 ult_text(), sqli
288a0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 te3_result_text1
288b0 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6(),.** sqlite3_
288c0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 result_text16le(
288d0 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 ), and sqlite3_r
288e0 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 esult_text16be()
288f0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 interfaces.** s
28900 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 et the return va
28910 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 lue of the appli
28920 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
28930 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a unction to be.**
28940 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 a text string w
28950 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e hich is represen
28960 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 ted as UTF-8, UT
28970 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 F-16 native byte
28980 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 order,.** UTF-1
28990 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 6 little endian,
289a0 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 or UTF-16 big e
289b0 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 ndian, respectiv
289c0 65 6c 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 74 ely..** SQLite t
289d0 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65 akes the text re
289e0 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 sult from the ap
289f0 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a plication from.*
28a00 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 * the 2nd parame
28a10 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 ter of the sqlit
28a20 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 e3_result_text*
28a30 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 49 interfaces..** I
28a40 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 f the 3rd parame
28a50 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ter to the sqlit
28a60 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 e3_result_text*
28a70 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 interfaces.** is
28a80 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 negative, then
28a90 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 SQLite takes res
28aa0 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 ult text from th
28ab0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a e 2nd parameter.
28ac0 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 ** through the f
28ad0 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 irst zero charac
28ae0 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 ter..** If the 3
28af0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
28b00 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 the sqlite3_resu
28b10 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 lt_text* interfa
28b20 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 ces.** is non-ne
28b30 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 gative, then as
28b40 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 many bytes (not
28b50 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 characters) of t
28b60 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 he text.** point
28b70 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 ed to by the 2nd
28b80 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 parameter are t
28b90 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c aken as the appl
28ba0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a ication-defined.
28bb0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 ** function resu
28bc0 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 lt..** If the 4t
28bd0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
28be0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
28bf0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 t_text* interfac
28c00 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 es.** or sqlite3
28c10 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 _result_blob is
28c20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 a non-NULL point
28c30 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 er, then SQLite
28c40 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 calls that.** fu
28c50 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 nction as the de
28c60 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 structor on the
28c70 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 text or BLOB res
28c80 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a ult when it has.
28c90 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e ** finished usin
28ca0 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a g that result..*
28cb0 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72 * If the 4th par
28cc0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 ameter to the sq
28cd0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
28ce0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 t* interfaces or
28cf0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 to.** sqlite3_r
28d00 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 esult_blob is th
28d10 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 e special consta
28d20 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 nt SQLITE_STATIC
28d30 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a , then SQLite.**
28d40 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 assumes that th
28d50 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 e text or BLOB r
28d60 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 esult is in cons
28d70 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 tant space and d
28d80 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 oes not.** copy
28d90 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 the content of t
28da0 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 he parameter nor
28db0 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 call a destruct
28dc0 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e or on the conten
28dd0 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73 t.** when it has
28de0 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 finished using
28df0 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 that result..**
28e00 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d If the 4th param
28e10 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 eter to the sqli
28e20 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a te3_result_text*
28e30 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f interfaces.** o
28e40 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 r sqlite3_result
28e50 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 _blob is the spe
28e60 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 cial constant SQ
28e70 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a LITE_TRANSIENT.*
28e80 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 * then SQLite ma
28e90 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 kes a copy of th
28ea0 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 e result into sp
28eb0 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f ace obtained fro
28ec0 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 m.** from [sqlit
28ed0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 e3_malloc()] bef
28ee0 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a ore it returns..
28ef0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
28f00 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 3_result_value()
28f10 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 interface sets
28f20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a the result of.**
28f30 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
28f40 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
28f50 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 n to be a copy t
28f60 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 he.** [unprotect
28f70 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
28f80 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 ] object specifi
28f90 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 ed by the 2nd pa
28fa0 72 61 6d 65 74 65 72 2e 20 20 54 68 65 0a 2a 2a rameter. The.**
28fb0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
28fc0 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 value() interfac
28fd0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f e makes a copy o
28fe0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 f the [sqlite3_v
28ff0 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 alue].** so that
29000 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 the [sqlite3_va
29010 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 lue] specified i
29020 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 n the parameter
29030 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a may change or.**
29040 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 be deallocated
29050 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 after sqlite3_re
29060 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 sult_value() ret
29070 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 urns without har
29080 6d 2e 0a 2a 2a 20 41 20 5b 70 72 6f 74 65 63 74 m..** A [protect
29090 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
290a0 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 ] object may alw
290b0 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72 ays be used wher
290c0 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 e an.** [unprote
290d0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
290e0 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 ue] object is re
290f0 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 quired, so eithe
29100 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 r.** kind of [sq
29110 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
29120 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 ect can be used
29130 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 with this interf
29140 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ace..**.** If th
29150 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
29160 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 called from wit
29170 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e hin the differen
29180 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e t thread.** than
29190 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e the one contain
291a0 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 ing the applicat
291b0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
291c0 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 tion that receiv
291d0 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 ed.** the [sqlit
291e0 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e e3_context] poin
291f0 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 ter, the results
29200 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a are undefined..
29210 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
29220 74 73 3a 0a 2a 2a 20 5b 48 31 36 34 30 33 5d 20 ts:.** [H16403]
29230 5b 48 31 36 34 30 36 5d 20 5b 48 31 36 34 30 39 [H16406] [H16409
29240 5d 20 5b 48 31 36 34 31 32 5d 20 5b 48 31 36 34 ] [H16412] [H164
29250 31 35 5d 20 5b 48 31 36 34 31 38 5d 20 5b 48 31 15] [H16418] [H1
29260 36 34 32 31 5d 20 5b 48 31 36 34 32 34 5d 0a 2a 6421] [H16424].*
29270 2a 20 5b 48 31 36 34 32 37 5d 20 5b 48 31 36 34 * [H16427] [H164
29280 33 30 5d 20 5b 48 31 36 34 33 33 5d 20 5b 48 31 30] [H16433] [H1
29290 36 34 33 36 5d 20 5b 48 31 36 34 33 39 5d 20 5b 6436] [H16439] [
292a0 48 31 36 34 34 32 5d 20 5b 48 31 36 34 34 35 5d H16442] [H16445]
292b0 20 5b 48 31 36 34 34 38 5d 0a 2a 2a 20 5b 48 31 [H16448].** [H1
292c0 36 34 35 31 5d 20 5b 48 31 36 34 35 34 5d 20 5b 6451] [H16454] [
292d0 48 31 36 34 35 37 5d 20 5b 48 31 36 34 36 30 5d H16457] [H16460]
292e0 20 5b 48 31 36 34 36 33 5d 0a 2a 2f 0a 53 51 4c [H16463].*/.SQL
292f0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c ITE_API void sql
29300 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 ite3_result_blob
29310 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
29320 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 *, const void*,
29330 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 int, void(*)(voi
29340 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 d*));.SQLITE_API
29350 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 void sqlite3_re
29360 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 sult_double(sqli
29370 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f te3_context*, do
29380 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 uble);.SQLITE_AP
29390 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 I void sqlite3_r
293a0 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 esult_error(sqli
293b0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f te3_context*, co
293c0 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b nst char*, int);
293d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
293e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
293f0 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f error16(sqlite3_
29400 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
29410 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c void*, int);.SQL
29420 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c ITE_API void sql
29430 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
29440 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 r_toobig(sqlite3
29450 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 _context*);.SQLI
29460 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 TE_API void sqli
29470 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
29480 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 _nomem(sqlite3_c
29490 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 ontext*);.SQLITE
294a0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 _API void sqlite
294b0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 3_result_error_c
294c0 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ode(sqlite3_cont
294d0 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 ext*, int);.SQLI
294e0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 TE_API void sqli
294f0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 te3_result_int(s
29500 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
29510 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 int);.SQLITE_AP
29520 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 I void sqlite3_r
29530 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 esult_int64(sqli
29540 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 te3_context*, sq
29550 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 lite3_int64);.SQ
29560 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 LITE_API void sq
29570 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c lite3_result_nul
29580 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 l(sqlite3_contex
29590 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 t*);.SQLITE_API
295a0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
295b0 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 ult_text(sqlite3
295c0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 _context*, const
295d0 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 char*, int, voi
295e0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 d(*)(void*));.SQ
295f0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 LITE_API void sq
29600 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
29610 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 t16(sqlite3_cont
29620 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 ext*, const void
29630 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 *, int, void(*)(
29640 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f void*));.SQLITE_
29650 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 API void sqlite3
29660 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 _result_text16le
29670 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
29680 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 *, const void*,
29690 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 int,void(*)(void
296a0 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 *));.SQLITE_API
296b0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
296c0 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c ult_text16be(sql
296d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 ite3_context*, c
296e0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c onst void*, int,
296f0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b void(*)(void*));
29700 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
29710 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
29720 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f value(sqlite3_co
29730 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f ntext*, sqlite3_
29740 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f value*);.SQLITE_
29750 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 API void sqlite3
29760 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 _result_zeroblob
29770 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
29780 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a *, int n);../*.*
29790 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 * CAPI3REF: Defi
297a0 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 ne New Collating
297b0 20 53 65 71 75 65 6e 63 65 73 20 7b 48 31 36 36 Sequences {H166
297c0 30 30 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 00} <S20300>.**.
297d0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f ** These functio
297e0 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 ns are used to a
297f0 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e dd new collation
29800 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74 68 sequences to th
29810 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 e.** [database c
29820 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 onnection] speci
29830 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73 fied as the firs
29840 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a t argument..**.*
29850 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 * The name of th
29860 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 e new collation
29870 73 65 71 75 65 6e 63 65 20 69 73 20 73 70 65 63 sequence is spec
29880 69 66 69 65 64 20 61 73 20 61 20 55 54 46 2d 38 ified as a UTF-8
29890 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 string.** for s
298a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
298b0 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 llation() and sq
298c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
298d0 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 lation_v2().** a
298e0 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 nd a UTF-16 stri
298f0 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 ng for sqlite3_c
29900 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 reate_collation1
29910 36 28 29 2e 20 49 6e 20 61 6c 6c 20 63 61 73 65 6(). In all case
29920 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 s.** the name is
29930 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 passed as the s
29940 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 econd function a
29950 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 rgument..**.** T
29960 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e he third argumen
29970 74 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 t may be one of
29980 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 the constants [S
29990 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 QLITE_UTF8],.**
299a0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d [SQLITE_UTF16LE]
299b0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 , or [SQLITE_UTF
299c0 31 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 16BE], indicatin
299d0 67 20 74 68 61 74 20 74 68 65 20 75 73 65 72 2d g that the user-
299e0 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 supplied.** rout
299f0 69 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20 62 ine expects to b
29a00 65 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72 e passed pointer
29a10 73 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 s to strings enc
29a20 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 oded using UTF-8
29a30 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 ,.** UTF-16 litt
29a40 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 le-endian, or UT
29a50 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 2c F-16 big-endian,
29a60 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 54 respectively. T
29a70 68 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67 75 he.** third argu
29a80 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f 20 ment might also
29a90 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 be [SQLITE_UTF16
29aa0 5d 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 ] to indicate th
29ab0 61 74 20 74 68 65 20 72 6f 75 74 69 6e 65 0a 2a at the routine.*
29ac0 2a 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74 65 * expects pointe
29ad0 72 73 20 74 6f 20 62 65 20 55 54 46 2d 31 36 20 rs to be UTF-16
29ae0 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 6e strings in the n
29af0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
29b00 2c 20 6f 72 20 74 68 65 0a 2a 2a 20 61 72 67 75 , or the.** argu
29b10 6d 65 6e 74 20 63 61 6e 20 62 65 20 5b 53 51 4c ment can be [SQL
29b20 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 ITE_UTF16_ALIGNE
29b30 44 5d 20 69 66 20 74 68 65 0a 2a 2a 20 74 68 65 D] if the.** the
29b40 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 routine expects
29b50 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 31 36 2d pointers to 16-
29b60 62 69 74 20 77 6f 72 64 20 61 6c 69 67 6e 65 64 bit word aligned
29b70 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 strings.** of U
29b80 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 TF-16 in the nat
29b90 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a ive byte order..
29ba0 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 **.** A pointer
29bb0 74 6f 20 74 68 65 20 75 73 65 72 20 73 75 70 70 to the user supp
29bc0 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75 73 lied routine mus
29bd0 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 t be passed as t
29be0 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67 75 he fifth.** argu
29bf0 6d 65 6e 74 2e 20 20 49 66 20 69 74 20 69 73 20 ment. If it is
29c00 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20 74 68 NULL, this is th
29c10 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65 74 69 e same as deleti
29c20 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e ng the collation
29c30 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28 73 6f .** sequence (so
29c40 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e that SQLite can
29c50 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e 79 6d not call it anym
29c60 6f 72 65 29 2e 0a 2a 2a 20 45 61 63 68 20 74 69 ore)..** Each ti
29c70 6d 65 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 me the applicati
29c80 6f 6e 20 73 75 70 70 6c 69 65 64 20 66 75 6e 63 on supplied func
29c90 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c tion is invoked,
29ca0 20 69 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a it is passed.**
29cb0 20 61 73 20 69 74 73 20 66 69 72 73 74 20 70 61 as its first pa
29cc0 72 61 6d 65 74 65 72 20 61 20 63 6f 70 79 20 6f rameter a copy o
29cd0 66 20 74 68 65 20 76 6f 69 64 2a 20 70 61 73 73 f the void* pass
29ce0 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 ed as the fourth
29cf0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 argument.** to
29d00 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
29d10 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 20 73 71 ollation() or sq
29d20 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
29d30 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a lation16()..**.*
29d40 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 * The remaining
29d50 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 arguments to the
29d60 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 application-sup
29d70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 61 72 plied routine ar
29d80 65 20 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a e two strings,.*
29d90 2a 20 65 61 63 68 20 72 65 70 72 65 73 65 6e 74 * each represent
29da0 65 64 20 62 79 20 61 20 28 6c 65 6e 67 74 68 2c ed by a (length,
29db0 20 64 61 74 61 29 20 70 61 69 72 20 61 6e 64 20 data) pair and
29dc0 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 20 65 encoded in the e
29dd0 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20 ncoding.** that
29de0 77 61 73 20 70 61 73 73 65 64 20 61 73 20 74 68 was passed as th
29df0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 e third argument
29e00 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 when the collat
29e10 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 61 73 ion sequence was
29e20 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 2e 20 .** registered.
29e30 7b 45 4e 44 7d 20 20 54 68 65 20 61 70 70 6c 69 {END} The appli
29e40 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 63 cation defined c
29e50 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 ollation routine
29e60 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 should.** retur
29e70 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f n negative, zero
29e80 20 6f 72 20 70 6f 73 69 74 69 76 65 20 69 66 20 or positive if
29e90 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 the first string
29ea0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 0a 2a is less than,.*
29eb0 2a 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 * equal to, or g
29ec0 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 reater than the
29ed0 73 65 63 6f 6e 64 20 73 74 72 69 6e 67 2e 20 69 second string. i
29ee0 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d 20 53 .e. (STRING1 - S
29ef0 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 TRING2)..**.** T
29f00 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 he sqlite3_creat
29f10 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 e_collation_v2()
29f20 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 works like sqli
29f30 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
29f40 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 tion().** except
29f50 20 74 68 61 74 20 69 74 20 74 61 6b 65 73 20 61 that it takes a
29f60 6e 20 65 78 74 72 61 20 61 72 67 75 6d 65 6e 74 n extra argument
29f70 20 77 68 69 63 68 20 69 73 20 61 20 64 65 73 74 which is a dest
29f80 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 ructor for.** th
29f90 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 e collation. Th
29fa0 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 e destructor is
29fb0 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 called when the
29fc0 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 collation is.**
29fd0 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 69 73 destroyed and is
29fe0 20 70 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f passed a copy o
29ff0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 f the fourth par
2a000 61 6d 65 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 ameter void* poi
2a010 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 nter.** of the s
2a020 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
2a030 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a llation_v2()..**
2a040 20 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 Collations are
2a050 64 65 73 74 72 6f 79 65 64 20 77 68 65 6e 20 74 destroyed when t
2a060 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 hey are overridd
2a070 65 6e 20 62 79 20 6c 61 74 65 72 20 63 61 6c 6c en by later call
2a080 73 20 74 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c s to the.** coll
2a090 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 ation creation f
2a0a0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e unctions or when
2a0b0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
2a0c0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c onnection] is cl
2a0d0 6f 73 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 osed.** using [s
2a0e0 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e qlite3_close()].
2a0f0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
2a100 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 [sqlite3_colla
2a110 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 tion_needed()] a
2a120 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c nd [sqlite3_coll
2a130 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 ation_needed16()
2a140 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 ]..**.** Require
2a150 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 36 30 ments:.** [H1660
2a160 33 5d 20 5b 48 31 36 36 30 34 5d 20 5b 48 31 36 3] [H16604] [H16
2a170 36 30 36 5d 20 5b 48 31 36 36 30 39 5d 20 5b 48 606] [H16609] [H
2a180 31 36 36 31 32 5d 20 5b 48 31 36 36 31 35 5d 20 16612] [H16615]
2a190 5b 48 31 36 36 31 38 5d 20 5b 48 31 36 36 32 31 [H16618] [H16621
2a1a0 5d 0a 2a 2a 20 5b 48 31 36 36 32 34 5d 20 5b 48 ].** [H16624] [H
2a1b0 31 36 36 32 37 5d 20 5b 48 31 36 36 33 30 5d 0a 16627] [H16630].
2a1c0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
2a1d0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 t sqlite3_create
2a1e0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 _collation(. sq
2a1f0 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 lite3*, . const
2a200 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 char *zName, .
2a210 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a int eTextRep, .
2a220 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a void*,. int(*
2a230 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c xCompare)(void*,
2a240 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c int,const void*,
2a250 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 int,const void*)
2a260 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .);.SQLITE_API i
2a270 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 nt sqlite3_creat
2a280 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a e_collation_v2(.
2a290 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 sqlite3*, . c
2a2a0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
2a2b0 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 , . int eTextRe
2a2c0 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 p, . void*,. i
2a2d0 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f nt(*xCompare)(vo
2a2e0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f id*,int,const vo
2a2f0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f id*,int,const vo
2a300 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 id*),. void(*xD
2a310 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 estroy)(void*).)
2a320 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
2a330 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
2a340 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 collation16(. s
2a350 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 qlite3*, . cons
2a360 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 t void *zName,.
2a370 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a int eTextRep, .
2a380 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a void*,. int(*
2a390 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c xCompare)(void*,
2a3a0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c int,const void*,
2a3b0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 int,const void*)
2a3c0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
2a3d0 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e REF: Collation N
2a3e0 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 20 eeded Callbacks
2a3f0 7b 48 31 36 37 30 30 7d 20 3c 53 32 30 33 30 30 {H16700} <S20300
2a400 3e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 >.**.** To avoid
2a410 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 having to regis
2a420 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f ter all collatio
2a430 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f n sequences befo
2a440 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a re a database.**
2a450 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 can be used, a
2a460 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 single callback
2a470 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 function may be
2a480 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 registered with
2a490 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 the.** [database
2a4a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 connection] to
2a4b0 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 76 be called whenev
2a4c0 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 er an undefined
2a4d0 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 collation.** seq
2a4e0 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 uence is require
2a4f0 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 d..**.** If the
2a500 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 function is regi
2a510 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 stered using the
2a520 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 sqlite3_collati
2a530 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c on_needed() API,
2a540 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 .** then it is p
2a550 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 assed the names
2a560 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c of undefined col
2a570 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 lation sequences
2a580 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 as strings.** e
2a590 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e ncoded in UTF-8.
2a5a0 20 7b 48 31 36 37 30 33 7d 20 49 66 20 73 71 6c {H16703} If sql
2a5b0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e ite3_collation_n
2a5c0 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65 eeded16() is use
2a5d0 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 d,.** the names
2a5e0 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54 are passed as UT
2a5f0 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 F-16 in machine
2a600 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
2a610 72 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 r..** A call to
2a620 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 either function
2a630 72 65 70 6c 61 63 65 73 20 61 6e 79 20 65 78 69 replaces any exi
2a640 73 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2e 0a sting callback..
2a650 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 **.** When the c
2a660 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
2a670 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 ed, the first ar
2a680 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 gument passed is
2a690 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 a copy.** of th
2a6a0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
2a6b0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c t to sqlite3_col
2a6c0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 lation_needed()
2a6d0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f or.** sqlite3_co
2a6e0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 llation_needed16
2a6f0 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 (). The second
2a700 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 argument is the
2a710 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
2a720 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 ection. The thi
2a730 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f rd argument is o
2a740 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 ne of [SQLITE_UT
2a750 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 F8], [SQLITE_UTF
2a760 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 16BE],.** or [SQ
2a770 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 LITE_UTF16LE], i
2a780 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f ndicating the mo
2a790 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 st desirable for
2a7a0 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 m of the collati
2a7b0 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 on.** sequence f
2a7c0 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 unction required
2a7d0 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 . The fourth pa
2a7e0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e rameter is the n
2a7f0 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 ame of the.** re
2a800 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e quired collation
2a810 20 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a sequence..**.**
2a820 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 The callback fu
2a830 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 nction should re
2a840 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72 gister the desir
2a850 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 ed collation usi
2a860 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 ng.** [sqlite3_c
2a870 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 reate_collation(
2a880 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 )], [sqlite3_cre
2a890 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 ate_collation16(
2a8a0 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 )], or.** [sqlit
2a8b0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
2a8c0 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a ion_v2()]..**.**
2a8d0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
2a8e0 2a 20 5b 48 31 36 37 30 32 5d 20 5b 48 31 36 37 * [H16702] [H167
2a8f0 30 34 5d 20 5b 48 31 36 37 30 36 5d 0a 2a 2f 0a 04] [H16706].*/.
2a900 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
2a910 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
2a920 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 _needed(. sqlit
2a930 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a e3*, . void*, .
2a940 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c void(*)(void*,
2a950 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 sqlite3*,int eTe
2a960 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 xtRep,const char
2a970 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 *).);.SQLITE_API
2a980 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c int sqlite3_col
2a990 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 lation_needed16(
2a9a0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 . sqlite3*, .
2a9b0 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 void*,. void(*)
2a9c0 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c (void*,sqlite3*,
2a9d0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e int eTextRep,con
2a9e0 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a st void*).);../*
2a9f0 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 .** Specify the
2aa00 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 key for an encry
2aa10 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 pted database.
2aa20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f This routine sho
2aa30 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 uld be.** called
2aa40 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c right after sql
2aa50 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a ite3_open()..**.
2aa60 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 ** The code to i
2aa70 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 mplement this AP
2aa80 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 I is not availab
2aa90 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 le in the public
2aaa0 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 release.** of S
2aab0 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 QLite..*/.SQLITE
2aac0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
2aad0 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 _key(. sqlite3
2aae0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
2aaf0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 /* Databa
2ab00 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 se to be rekeyed
2ab10 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 */. const void
2ab20 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 *pKey, int nKey
2ab30 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 /* The key
2ab40 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 */.);../*.** Cha
2ab50 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 nge the key on a
2ab60 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e n open database.
2ab70 20 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 If the current
2ab80 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 database is not
2ab90 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 .** encrypted, t
2aba0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c his routine will
2abb0 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 encrypt it. If
2abc0 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 pNew==0 or nNew
2abd0 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 ==0, the.** data
2abe0 62 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65 base is decrypte
2abf0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 d..**.** The cod
2ac00 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 e to implement t
2ac10 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 his API is not a
2ac20 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 vailable in the
2ac30 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a public release.*
2ac40 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a * of SQLite..*/.
2ac50 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
2ac60 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 qlite3_rekey(.
2ac70 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
2ac80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
2ac90 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 * Database to be
2aca0 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f rekeyed */. co
2acb0 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 nst void *pKey,
2acc0 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 int nKey /*
2acd0 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 The new key */.)
2ace0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2acf0 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 F: Suspend Execu
2ad00 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 tion For A Short
2ad10 20 54 69 6d 65 20 7b 48 31 30 35 33 30 7d 20 3c Time {H10530} <
2ad20 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S40410>.**.** Th
2ad30 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 e sqlite3_sleep(
2ad40 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 ) function cause
2ad50 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 s the current th
2ad60 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 read to suspend
2ad70 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 execution.** for
2ad80 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 at least a numb
2ad90 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e er of millisecon
2ada0 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 ds specified in
2adb0 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a its parameter..*
2adc0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 *.** If the oper
2add0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 ating system doe
2ade0 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c s not support sl
2adf0 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74 eep requests wit
2ae00 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 h.** millisecond
2ae10 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e time resolution
2ae20 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 , then the time
2ae30 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 will be rounded
2ae40 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 up to.** the nea
2ae50 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 rest second. The
2ae60 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 number of milli
2ae70 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 seconds of sleep
2ae80 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 actually.** req
2ae90 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 uested from the
2aea0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d operating system
2aeb0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
2aec0 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 .** SQLite imple
2aed0 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 ments this inter
2aee0 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 face by calling
2aef0 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 the xSleep().**
2af00 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 method of the de
2af10 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 fault [sqlite3_v
2af20 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a fs] object..**.*
2af30 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 * Requirements:
2af40 5b 48 31 30 35 33 33 5d 20 5b 48 31 30 35 33 36 [H10533] [H10536
2af50 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
2af60 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 int sqlite3_slee
2af70 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 p(int);../*.** C
2af80 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 API3REF: Name Of
2af90 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 The Folder Hold
2afa0 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 ing Temporary Fi
2afb0 6c 65 73 20 7b 48 31 30 33 31 30 7d 20 3c 53 32 les {H10310} <S2
2afc0 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 0000>.**.** If t
2afd0 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 his global varia
2afe0 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 ble is made to p
2aff0 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 oint to a string
2b000 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 which is.** the
2b010 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 name of a folde
2b020 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 r (a.k.a. direct
2b030 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 ory), then all t
2b040 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a emporary files.*
2b050 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c * created by SQL
2b060 69 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 ite will be plac
2b070 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 ed in that direc
2b080 74 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20 76 tory. If this v
2b090 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 ariable.** is a
2b0a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 NULL pointer, th
2b0b0 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72 en SQLite perfor
2b0c0 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 ms a search for
2b0d0 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a an appropriate.*
2b0e0 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 * temporary file
2b0f0 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a directory..**.*
2b100 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 * It is not safe
2b110 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 to read or modi
2b120 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 fy this variable
2b130 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e in more than on
2b140 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61 e.** thread at a
2b150 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f time. It is no
2b160 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f t safe to read o
2b170 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 r modify this va
2b180 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b riable.** if a [
2b190 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2b1a0 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73 ion] is being us
2b1b0 65 64 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 ed at the same t
2b1c0 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61 74 ime in a separat
2b1d0 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 e.** thread..**
2b1e0 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 It is intended t
2b1f0 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c hat this variabl
2b200 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a e be set once.**
2b210 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 as part of proc
2b220 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 ess initializati
2b230 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e on and before an
2b240 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 y SQLite interfa
2b250 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 ce.** routines h
2b260 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 ave been called
2b270 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 76 61 and that this va
2b280 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e riable remain un
2b290 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 changed.** there
2b2a0 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 after..**.** The
2b2b0 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 [temp_store_dir
2b2c0 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d ectory pragma] m
2b2d0 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 ay modify this v
2b2e0 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 ariable and caus
2b2f0 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 e.** it to point
2b300 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 to memory obtai
2b310 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ned from [sqlite
2b320 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 46 75 72 74 3_malloc]. Furt
2b330 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 hermore,.** the
2b340 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 [temp_store_dire
2b350 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c ctory pragma] al
2b360 77 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 ways assumes tha
2b370 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 t any string.**
2b380 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 that this variab
2b390 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 le points to is
2b3a0 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f held in memory o
2b3b0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a btained from .**
2b3c0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
2b3d0 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 ] and the pragma
2b3e0 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 may attempt to
2b3f0 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 free that memory
2b400 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 .** using [sqlit
2b410 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e e3_free]..** Hen
2b420 63 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 ce, if this vari
2b430 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 able is modified
2b440 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 directly, eithe
2b450 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a r it should be.*
2b460 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d * made NULL or m
2b470 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 ade to point to
2b480 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 memory obtained
2b490 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 from [sqlite3_ma
2b4a0 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 lloc].** or else
2b4b0 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 the use of the
2b4c0 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 [temp_store_dire
2b4d0 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 ctory pragma] sh
2b4e0 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e ould be avoided.
2b4f0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 .*/.SQLITE_API S
2b500 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 QLITE_EXTERN cha
2b510 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f r *sqlite3_temp_
2b520 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a directory;../*.*
2b530 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 * CAPI3REF: Test
2b540 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 For Auto-Commit
2b550 20 4d 6f 64 65 20 7b 48 31 32 39 33 30 7d 20 3c Mode {H12930} <
2b560 53 36 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f S60200>.** KEYWO
2b570 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 RDS: {autocommit
2b580 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 mode}.**.** The
2b590 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 sqlite3_get_aut
2b5a0 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 ocommit() interf
2b5b0 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d ace returns non-
2b5c0 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 zero or.** zero
2b5d0 69 66 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 if the given dat
2b5e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2b5f0 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e is or is not in
2b600 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 autocommit mode
2b610 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c ,.** respectivel
2b620 79 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d y. Autocommit m
2b630 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 ode is on by def
2b640 61 75 6c 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d ault..** Autocom
2b650 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 mit mode is disa
2b660 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e bled by a [BEGIN
2b670 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 ] statement..**
2b680 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 Autocommit mode
2b690 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 is re-enabled by
2b6a0 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b a [COMMIT] or [
2b6b0 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a ROLLBACK]..**.**
2b6c0 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 If certain kind
2b6d0 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 s of errors occu
2b6e0 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 r on a statement
2b6f0 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d within a multi-
2b700 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 statement.** tra
2b710 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 nsaction (errors
2b720 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 including [SQLI
2b730 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 TE_FULL], [SQLIT
2b740 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 E_IOERR],.** [SQ
2b750 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 LITE_NOMEM], [SQ
2b760 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 LITE_BUSY], and
2b770 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 [SQLITE_INTERRUP
2b780 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 T]) then the.**
2b790 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 transaction migh
2b7a0 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b t be rolled back
2b7b0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 automatically.
2b7c0 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f The only way to
2b7d0 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 .** find out whe
2b7e0 74 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f ther SQLite auto
2b7f0 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 matically rolled
2b800 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 back the transa
2b810 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 ction after.** a
2b820 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 n error is to us
2b830 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e e this function.
2b840 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 .**.** If anothe
2b850 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 r thread changes
2b860 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 the autocommit
2b870 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 status of the da
2b880 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 tabase.** connec
2b890 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 tion while this
2b8a0 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 routine is runni
2b8b0 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 ng, then the ret
2b8c0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 urn value.** is
2b8d0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
2b8e0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b Requirements: [
2b8f0 48 31 32 39 33 31 5d 20 5b 48 31 32 39 33 32 5d H12931] [H12932]
2b900 20 5b 48 31 32 39 33 33 5d 20 5b 48 31 32 39 33 [H12933] [H1293
2b910 34 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 4].*/.SQLITE_API
2b920 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 int sqlite3_get
2b930 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 _autocommit(sqli
2b940 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 te3*);../*.** CA
2b950 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65 PI3REF: Find The
2b960 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 Database Handle
2b970 20 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 53 Of A Prepared S
2b980 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 31 32 30 tatement {H13120
2b990 7d 20 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a 2a 2a } <S60600>.**.**
2b9a0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f The sqlite3_db_
2b9b0 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 handle interface
2b9c0 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61 returns the [da
2b9d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2b9e0 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 n] handle.** to
2b9f0 77 68 69 63 68 20 61 20 5b 70 72 65 70 61 72 65 which a [prepare
2ba00 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c d statement] bel
2ba10 6f 6e 67 73 2e 20 20 54 68 65 20 5b 64 61 74 61 ongs. The [data
2ba20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
2ba30 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 .** returned by
2ba40 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c sqlite3_db_handl
2ba50 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64 e is the same [d
2ba60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2ba70 6f 6e 5d 20 74 68 61 74 20 77 61 73 20 74 68 65 on] that was the
2ba80 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a first argument.
2ba90 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 ** to the [sqlit
2baa0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
2bab0 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 call (or its va
2bac0 72 69 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 riants) that was
2bad0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 used to.** crea
2bae0 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 te the statement
2baf0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c in the first pl
2bb00 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 ace..**.** Requi
2bb10 72 65 6d 65 6e 74 73 3a 20 5b 48 31 33 31 32 33 rements: [H13123
2bb20 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
2bb30 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 sqlite3 *sqlite3
2bb40 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 _db_handle(sqlit
2bb50 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a e3_stmt*);../*.*
2bb60 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 * CAPI3REF: Find
2bb70 20 74 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 the next prepar
2bb80 65 64 20 73 74 61 74 65 6d 65 6e 74 20 7b 48 31 ed statement {H1
2bb90 33 31 34 30 7d 20 3c 53 36 30 36 30 30 3e 0a 2a 3140} <S60600>.*
2bba0 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 *.** This interf
2bbb0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f ace returns a po
2bbc0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78 inter to the nex
2bbd0 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 t [prepared stat
2bbe0 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 ement] after.**
2bbf0 70 53 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64 pStmt associated
2bc00 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 with the [datab
2bc10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
2bc20 70 44 62 2e 20 20 49 66 20 70 53 74 6d 74 20 69 pDb. If pStmt i
2bc30 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 s NULL.** then t
2bc40 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 his interface re
2bc50 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
2bc60 74 6f 20 74 68 65 20 66 69 72 73 74 20 70 72 65 to the first pre
2bc70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a pared statement.
2bc80 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ** associated wi
2bc90 74 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 th the database
2bca0 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 connection pDb.
2bcb0 20 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20 If no prepared
2bcc0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 statement.** sat
2bcd0 69 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69 isfies the condi
2bce0 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f tions of this ro
2bcf0 75 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e utine, it return
2bd00 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 s NULL..**.** Th
2bd10 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
2bd20 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 ection] pointer
2bd30 44 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a D in a call to.*
2bd40 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f * [sqlite3_next_
2bd50 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20 stmt(D,S)] must
2bd60 72 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e refer to an open
2bd70 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e database.** con
2bd80 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70 nection and in p
2bd90 61 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20 6e articular must n
2bda0 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 ot be a NULL poi
2bdb0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 nter..**.** Requ
2bdc0 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 33 31 34 irements: [H1314
2bdd0 33 5d 20 5b 48 31 33 31 34 36 5d 20 5b 48 31 33 3] [H13146] [H13
2bde0 31 34 39 5d 20 5b 48 31 33 31 35 32 5d 0a 2a 2f 149] [H13152].*/
2bdf0 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 .SQLITE_API sqli
2be00 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 te3_stmt *sqlite
2be10 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 3_next_stmt(sqli
2be20 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 te3 *pDb, sqlite
2be30 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 3_stmt *pStmt);.
2be40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2be50 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c Commit And Roll
2be60 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f back Notificatio
2be70 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 n Callbacks {H12
2be80 39 35 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 950} <S60400>.**
2be90 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
2bea0 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e commit_hook() in
2beb0 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 terface register
2bec0 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 s a callback.**
2bed0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 function to be i
2bee0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 nvoked whenever
2bef0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 a transaction is
2bf00 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 [COMMIT | commi
2bf10 74 74 65 64 5d 2e 0a 2a 2a 20 41 6e 79 20 63 61 tted]..** Any ca
2bf20 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 llback set by a
2bf30 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f previous call to
2bf40 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f sqlite3_commit_
2bf50 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 hook().** for th
2bf60 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 e same database
2bf70 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 connection is ov
2bf80 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 erridden..** The
2bf90 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 sqlite3_rollbac
2bfa0 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 k_hook() interfa
2bfb0 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 ce registers a c
2bfc0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 allback.** funct
2bfd0 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 ion to be invoke
2bfe0 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 d whenever a tra
2bff0 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 52 4f 4c nsaction is [ROL
2c000 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 62 LBACK | rolled b
2c010 61 63 6b 5d 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c ack]..** Any cal
2c020 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 lback set by a p
2c030 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 revious call to
2c040 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 sqlite3_commit_h
2c050 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 ook().** for the
2c060 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 same database c
2c070 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 onnection is ove
2c080 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 rridden..** The
2c090 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73 pArg argument is
2c0a0 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 passed through
2c0b0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e to the callback.
2c0c0 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62 .** If the callb
2c0d0 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 ack on a commit
2c0e0 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 hook function re
2c0f0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a turns non-zero,.
2c100 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d ** then the comm
2c110 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 it is converted
2c120 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e into a rollback.
2c130 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 .**.** If anothe
2c140 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 r function was p
2c150 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 reviously regist
2c160 65 72 65 64 2c 20 69 74 73 0a 2a 2a 20 70 41 72 ered, its.** pAr
2c170 67 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 g value is retur
2c180 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 ned. Otherwise
2c190 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 NULL is returned
2c1a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c ..**.** The call
2c1b0 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 back implementat
2c1c0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 ion must not do
2c1d0 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 anything that wi
2c1e0 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 ll modify.** the
2c1f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
2c200 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 tion that invoke
2c210 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 d the callback.
2c220 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 Any actions.**
2c230 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 to modify the da
2c240 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2c250 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 n must be deferr
2c260 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 ed until after t
2c270 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e he.** completion
2c280 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
2c290 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 _step()] call th
2c2a0 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 at triggered the
2c2b0 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f commit.** or ro
2c2c0 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 llback hook in t
2c2d0 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a he first place..
2c2e0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 ** Note that [sq
2c2f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
2c300 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
2c310 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f _step()] both mo
2c320 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 dify their.** da
2c330 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2c340 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 ns for the meani
2c350 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 ng of "modify" i
2c360 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 n this paragraph
2c370 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 ..**.** Register
2c380 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 ing a NULL funct
2c390 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 ion disables the
2c3a0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a callback..**.**
2c3b0 20 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 When the commit
2c3c0 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72 hook callback r
2c3d0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a outine returns z
2c3e0 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54 ero, the [COMMIT
2c3f0 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69 ].** operation i
2c400 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e s allowed to con
2c410 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 tinue normally.
2c420 20 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 If the commit h
2c430 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e ook.** returns n
2c440 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 on-zero, then th
2c450 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f e [COMMIT] is co
2c460 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 5b nverted into a [
2c470 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 54 68 ROLLBACK]..** Th
2c480 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 e rollback hook
2c490 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 is invoked on a
2c4a0 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20 72 65 rollback that re
2c4b0 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d sults from a com
2c4c0 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 mit.** hook retu
2c4d0 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 rning non-zero,
2c4e0 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75 6c 64 just as it would
2c4f0 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f 74 68 be with any oth
2c500 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a er rollback..**.
2c510 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f ** For the purpo
2c520 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c ses of this API,
2c530 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 a transaction i
2c540 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 s said to have b
2c550 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 een.** rolled ba
2c560 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69 ck if an explici
2c570 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 t "ROLLBACK" sta
2c580 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 tement is execut
2c590 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 ed, or.** an err
2c5a0 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 or or constraint
2c5b0 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 causes an impli
2c5c0 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 cit rollback to
2c5d0 6f 63 63 75 72 2e 0a 2a 2a 20 54 68 65 20 72 6f occur..** The ro
2c5e0 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 llback callback
2c5f0 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 is not invoked i
2c600 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 f a transaction
2c610 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 is.** automatica
2c620 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 lly rolled back
2c630 62 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61 because the data
2c640 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
2c650 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 54 68 is closed..** Th
2c660 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 e rollback callb
2c670 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b ack is not invok
2c680 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 ed if a transact
2c690 69 6f 6e 20 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64 ion is.** rolled
2c6a0 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 61 20 back because a
2c6b0 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20 commit callback
2c6c0 72 65 74 75 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72 returned non-zer
2c6d0 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e 20 43 68 65 o..** <todo> Che
2c6e0 63 6b 20 6f 6e 20 74 68 69 73 20 3c 2f 74 6f 64 ck on this </tod
2c6f0 6f 3e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 o>.**.** See als
2c700 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 o the [sqlite3_u
2c710 70 64 61 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e pdate_hook()] in
2c720 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 52 terface..**.** R
2c730 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
2c740 5b 48 31 32 39 35 31 5d 20 5b 48 31 32 39 35 32 [H12951] [H12952
2c750 5d 20 5b 48 31 32 39 35 33 5d 20 5b 48 31 32 39 ] [H12953] [H129
2c760 35 34 5d 20 5b 48 31 32 39 35 35 5d 0a 2a 2a 20 54] [H12955].**
2c770 5b 48 31 32 39 36 31 5d 20 5b 48 31 32 39 36 32 [H12961] [H12962
2c780 5d 20 5b 48 31 32 39 36 33 5d 20 5b 48 31 32 39 ] [H12963] [H129
2c790 36 34 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 64].*/.SQLITE_AP
2c7a0 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f I void *sqlite3_
2c7b0 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 commit_hook(sqli
2c7c0 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 te3*, int(*)(voi
2c7d0 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c d*), void*);.SQL
2c7e0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 ITE_API void *sq
2c7f0 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 lite3_rollback_h
2c800 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f ook(sqlite3*, vo
2c810 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 id(*)(void *), v
2c820 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 oid*);../*.** CA
2c830 50 49 33 52 45 46 3a 20 44 61 74 61 20 43 68 61 PI3REF: Data Cha
2c840 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e nge Notification
2c850 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 Callbacks {H129
2c860 37 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 70} <S60400>.**.
2c870 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 ** The sqlite3_u
2c880 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 pdate_hook() int
2c890 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 erface registers
2c8a0 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 a callback func
2c8b0 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 tion.** with the
2c8c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
2c8d0 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65 ction] identifie
2c8e0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61 d by the first a
2c8f0 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 rgument.** to be
2c900 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 invoked wheneve
2c910 72 20 61 20 72 6f 77 20 69 73 20 75 70 64 61 74 r a row is updat
2c920 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 ed, inserted or
2c930 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 deleted..** Any
2c940 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 callback set by
2c950 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 a previous call
2c960 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e to this function
2c970 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 .** for the same
2c980 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
2c990 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 tion is overridd
2c9a0 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 en..**.** The se
2c9b0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 cond argument is
2c9c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
2c9d0 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e e function to in
2c9e0 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 voke when a.** r
2c9f0 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 ow is updated, i
2ca00 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 nserted or delet
2ca10 65 64 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 ed..** The first
2ca20 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
2ca30 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 callback is a c
2ca40 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 opy of the third
2ca50 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 argument.** to
2ca60 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 sqlite3_update_h
2ca70 6f 6f 6b 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 ook()..** The se
2ca80 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 cond callback ar
2ca90 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 gument is one of
2caa0 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d [SQLITE_INSERT]
2cab0 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 , [SQLITE_DELETE
2cac0 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 ],.** or [SQLITE
2cad0 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 _UPDATE], depend
2cae0 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 ing on the opera
2caf0 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 tion that caused
2cb00 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a the callback.**
2cb10 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a to be invoked..
2cb20 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 ** The third and
2cb30 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 fourth argument
2cb40 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 s to the callbac
2cb50 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 k contain pointe
2cb60 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 rs to the.** dat
2cb70 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 abase and table
2cb80 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 name containing
2cb90 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 the affected row
2cba0 2e 0a 2a 2a 20 54 68 65 20 66 69 6e 61 6c 20 63 ..** The final c
2cbb0 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 allback paramete
2cbc0 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d r is the [rowid]
2cbd0 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 of the row..**
2cbe0 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 In the case of a
2cbf0 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 n update, this i
2cc00 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 s the [rowid] af
2cc10 74 65 72 20 74 68 65 20 75 70 64 61 74 65 20 74 ter the update t
2cc20 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a akes place..**.*
2cc30 2a 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f * The update hoo
2cc40 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 k is not invoked
2cc50 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 when internal s
2cc60 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 ystem tables are
2cc70 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e .** modified (i.
2cc80 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 e. sqlite_master
2cc90 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 and sqlite_sequ
2cca0 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 ence)..**.** In
2ccb0 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c the current impl
2ccc0 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68 65 20 ementation, the
2ccd0 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 update hook.** i
2cce0 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 s not invoked wh
2ccf0 65 6e 20 64 75 70 6c 69 63 61 74 69 6f 6e 20 72 en duplication r
2cd00 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 ows are deleted
2cd10 62 65 63 61 75 73 65 20 6f 66 20 61 6e 0a 2a 2a because of an.**
2cd20 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 7c 20 [ON CONFLICT |
2cd30 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52 45 50 4c ON CONFLICT REPL
2cd40 41 43 45 5d 20 63 6c 61 75 73 65 2e 20 20 4e 6f ACE] clause. No
2cd50 72 20 69 73 20 74 68 65 20 75 70 64 61 74 65 20 r is the update
2cd60 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 hook.** invoked
2cd70 77 68 65 6e 20 72 6f 77 73 20 61 72 65 20 64 65 when rows are de
2cd80 6c 65 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 leted using the
2cd90 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 [truncate optimi
2cda0 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 zation]..** The
2cdb0 65 78 63 65 70 74 69 6f 6e 73 20 64 65 66 69 6e exceptions defin
2cdc0 65 64 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 ed in this parag
2cdd0 72 61 70 68 20 6d 69 67 68 74 20 63 68 61 6e 67 raph might chang
2cde0 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a e in a future.**
2cdf0 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 release of SQLi
2ce00 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 te..**.** The up
2ce10 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d date hook implem
2ce20 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f entation must no
2ce30 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 t do anything th
2ce40 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a at will modify.*
2ce50 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 * the database c
2ce60 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 onnection that i
2ce70 6e 76 6f 6b 65 64 20 74 68 65 20 75 70 64 61 74 nvoked the updat
2ce80 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 61 63 74 e hook. Any act
2ce90 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 ions.** to modif
2cea0 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 y the database c
2ceb0 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 onnection must b
2cec0 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c e deferred until
2ced0 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f after the.** co
2cee0 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 mpletion of the
2cef0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
2cf00 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 call that trigg
2cf10 65 72 65 64 20 74 68 65 20 75 70 64 61 74 65 20 ered the update
2cf20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 hook..** Note th
2cf30 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 at [sqlite3_prep
2cf40 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 are_v2()] and [s
2cf50 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 qlite3_step()] b
2cf60 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 oth modify their
2cf70 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
2cf80 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 nections for the
2cf90 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 meaning of "mod
2cfa0 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 ify" in this par
2cfb0 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 49 66 agraph..**.** If
2cfc0 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f another functio
2cfd0 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79 n was previously
2cfe0 20 72 65 67 69 73 74 65 72 65 64 2c 20 69 74 73 registered, its
2cff0 20 70 41 72 67 20 76 61 6c 75 65 0a 2a 2a 20 69 pArg value.** i
2d000 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 s returned. Oth
2d010 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 erwise NULL is r
2d020 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 eturned..**.** S
2d030 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c ee also the [sql
2d040 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b ite3_commit_hook
2d050 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
2d060 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 _rollback_hook()
2d070 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2e ].** interfaces.
2d080 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
2d090 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 39 37 31 5d nts:.** [H12971]
2d0a0 20 5b 48 31 32 39 37 33 5d 20 5b 48 31 32 39 37 [H12973] [H1297
2d0b0 35 5d 20 5b 48 31 32 39 37 37 5d 20 5b 48 31 32 5] [H12977] [H12
2d0c0 39 37 39 5d 20 5b 48 31 32 39 38 31 5d 20 5b 48 979] [H12981] [H
2d0d0 31 32 39 38 33 5d 20 5b 48 31 32 39 38 36 5d 0a 12983] [H12986].
2d0e0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f */.SQLITE_API vo
2d0f0 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 64 61 id *sqlite3_upda
2d100 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 te_hook(. sqlit
2d110 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 e3*, . void(*)(
2d120 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72 void *,int ,char
2d130 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f const *,char co
2d140 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e nst *,sqlite3_in
2d150 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b t64),. void*.);
2d160 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2d170 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 : Enable Or Disa
2d180 62 6c 65 20 53 68 61 72 65 64 20 50 61 67 65 72 ble Shared Pager
2d190 20 43 61 63 68 65 20 7b 48 31 30 33 33 30 7d 20 Cache {H10330}
2d1a0 3c 53 33 30 39 30 30 3e 0a 2a 2a 20 4b 45 59 57 <S30900>.** KEYW
2d1b0 4f 52 44 53 3a 20 7b 73 68 61 72 65 64 20 63 61 ORDS: {shared ca
2d1c0 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 che}.**.** This
2d1d0 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 routine enables
2d1e0 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 or disables the
2d1f0 73 68 61 72 69 6e 67 20 6f 66 20 74 68 65 20 64 sharing of the d
2d200 61 74 61 62 61 73 65 20 63 61 63 68 65 0a 2a 2a atabase cache.**
2d210 20 61 6e 64 20 73 63 68 65 6d 61 20 64 61 74 61 and schema data
2d220 20 73 74 72 75 63 74 75 72 65 73 20 62 65 74 77 structures betw
2d230 65 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f een [database co
2d240 6e 6e 65 63 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65 nnection | conne
2d250 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68 ctions].** to th
2d260 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e e same database.
2d270 20 53 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 Sharing is enab
2d280 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d led if the argum
2d290 65 6e 74 20 69 73 20 74 72 75 65 0a 2a 2a 20 61 ent is true.** a
2d2a0 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66 20 74 nd disabled if t
2d2b0 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 66 he argument is f
2d2c0 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20 43 61 63 68 alse..**.** Cach
2d2d0 65 20 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61 e sharing is ena
2d2e0 62 6c 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65 bled and disable
2d2f0 64 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20 d for an entire
2d300 70 72 6f 63 65 73 73 2e 0a 2a 2a 20 54 68 69 73 process..** This
2d310 20 69 73 20 61 20 63 68 61 6e 67 65 20 61 73 20 is a change as
2d320 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f of SQLite versio
2d330 6e 20 33 2e 35 2e 30 2e 20 49 6e 20 70 72 69 6f n 3.5.0. In prio
2d340 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 r versions of SQ
2d350 4c 69 74 65 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 Lite,.** sharing
2d360 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 was enabled or
2d370 64 69 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63 disabled for eac
2d380 68 20 74 68 72 65 61 64 20 73 65 70 61 72 61 74 h thread separat
2d390 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 ely..**.** The c
2d3a0 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 ache sharing mod
2d3b0 65 20 73 65 74 20 62 79 20 74 68 69 73 20 69 6e e set by this in
2d3c0 74 65 72 66 61 63 65 20 65 66 66 65 63 74 73 20 terface effects
2d3d0 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a all subsequent.*
2d3e0 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 * calls to [sqli
2d3f0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 te3_open()], [sq
2d400 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d lite3_open_v2()]
2d410 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f , and [sqlite3_o
2d420 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 pen16()]..** Exi
2d430 73 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 63 sting database c
2d440 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 onnections conti
2d450 6e 75 65 20 75 73 65 20 74 68 65 20 73 68 61 72 nue use the shar
2d460 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 ing mode.** that
2d470 20 77 61 73 20 69 6e 20 65 66 66 65 63 74 20 61 was in effect a
2d480 74 20 74 68 65 20 74 69 6d 65 20 74 68 65 79 20 t the time they
2d490 77 65 72 65 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a were opened..**.
2d4a0 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 ** Virtual table
2d4b0 73 20 63 61 6e 6e 6f 74 20 62 65 20 75 73 65 64 s cannot be used
2d4c0 20 77 69 74 68 20 61 20 73 68 61 72 65 64 20 63 with a shared c
2d4d0 61 63 68 65 2e 20 20 57 68 65 6e 20 73 68 61 72 ache. When shar
2d4e0 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 ed.** cache is e
2d4f0 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c nabled, the [sql
2d500 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 ite3_create_modu
2d510 6c 65 28 29 5d 20 41 50 49 20 75 73 65 64 20 74 le()] API used t
2d520 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 76 69 o register.** vi
2d530 72 74 75 61 6c 20 74 61 62 6c 65 73 20 77 69 6c rtual tables wil
2d540 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 l always return
2d550 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 an error..**.**
2d560 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 This routine ret
2d570 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d urns [SQLITE_OK]
2d580 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65 if shared cache
2d590 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 was enabled or
2d5a0 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63 disabled.** succ
2d5b0 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 essfully. An [e
2d5c0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 rror code] is re
2d5d0 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65 turned otherwise
2d5e0 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65 64 20 63 ..**.** Shared c
2d5f0 61 63 68 65 20 69 73 20 64 69 73 61 62 6c 65 64 ache is disabled
2d600 20 62 79 20 64 65 66 61 75 6c 74 2e 20 42 75 74 by default. But
2d610 20 74 68 69 73 20 6d 69 67 68 74 20 63 68 61 6e this might chan
2d620 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 ge in.** future
2d630 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 releases of SQLi
2d640 74 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e te. Application
2d650 73 20 74 68 61 74 20 63 61 72 65 20 61 62 6f 75 s that care abou
2d660 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 t shared.** cach
2d670 65 20 73 65 74 74 69 6e 67 20 73 68 6f 75 6c 64 e setting should
2d680 20 73 65 74 20 69 74 20 65 78 70 6c 69 63 69 74 set it explicit
2d690 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c ly..**.** See Al
2d6a0 73 6f 3a 20 20 5b 53 51 4c 69 74 65 20 53 68 61 so: [SQLite Sha
2d6b0 72 65 64 2d 43 61 63 68 65 20 4d 6f 64 65 5d 0a red-Cache Mode].
2d6c0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
2d6d0 74 73 3a 20 5b 48 31 30 33 33 31 5d 20 5b 48 31 ts: [H10331] [H1
2d6e0 30 33 33 36 5d 20 5b 48 31 30 33 33 37 5d 20 5b 0336] [H10337] [
2d6f0 48 31 30 33 33 39 5d 0a 2a 2f 0a 53 51 4c 49 54 H10339].*/.SQLIT
2d700 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
2d710 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 3_enable_shared_
2d720 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a cache(int);../*.
2d730 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 74 74 ** CAPI3REF: Att
2d740 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65 61 empt To Free Hea
2d750 70 20 4d 65 6d 6f 72 79 20 7b 48 31 37 33 34 30 p Memory {H17340
2d760 7d 20 3c 53 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a } <S30220>.**.**
2d770 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c The sqlite3_rel
2d780 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e ease_memory() in
2d790 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 terface attempts
2d7a0 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73 to free N bytes
2d7b0 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f .** of heap memo
2d7c0 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 ry by deallocati
2d7d0 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c ng non-essential
2d7e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
2d7f0 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74 ons.** held by t
2d800 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 72 he database libr
2d810 61 72 79 2e 20 7b 45 4e 44 7d 20 20 4d 65 6d 6f ary. {END} Memo
2d820 72 79 20 75 73 65 64 20 74 6f 20 63 61 63 68 65 ry used to cache
2d830 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 database.** pag
2d840 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 es to improve pe
2d850 72 66 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 rformance is an
2d860 65 78 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 example of non-e
2d870 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e ssential memory.
2d880 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 .** sqlite3_rele
2d890 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 ase_memory() ret
2d8a0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
2d8b0 6f 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c of bytes actuall
2d8c0 79 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 y freed,.** whic
2d8d0 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 h might be more
2d8e0 6f 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 or less than the
2d8f0 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 amount requeste
2d900 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 d..**.** Require
2d910 6d 65 6e 74 73 3a 20 5b 48 31 37 33 34 31 5d 20 ments: [H17341]
2d920 5b 48 31 37 33 34 32 5d 0a 2a 2f 0a 53 51 4c 49 [H17342].*/.SQLI
2d930 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
2d940 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 e3_release_memor
2d950 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 y(int);../*.** C
2d960 41 50 49 33 52 45 46 3a 20 49 6d 70 6f 73 65 20 API3REF: Impose
2d970 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 A Limit On Heap
2d980 53 69 7a 65 20 7b 48 31 37 33 35 30 7d 20 3c 53 Size {H17350} <S
2d990 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 30220>.**.** The
2d9a0 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 sqlite3_soft_he
2d9b0 61 70 5f 6c 69 6d 69 74 28 29 20 69 6e 74 65 72 ap_limit() inter
2d9c0 66 61 63 65 20 70 6c 61 63 65 73 20 61 20 22 73 face places a "s
2d9d0 6f 66 74 22 20 6c 69 6d 69 74 0a 2a 2a 20 6f 6e oft" limit.** on
2d9e0 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 the amount of h
2d9f0 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 eap memory that
2da00 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 may be allocated
2da10 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 49 by SQLite..** I
2da20 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c f an internal al
2da30 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72 65 71 75 location is requ
2da40 65 73 74 65 64 20 74 68 61 74 20 77 6f 75 6c 64 ested that would
2da50 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 73 exceed the.** s
2da60 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 oft heap limit,
2da70 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 [sqlite3_release
2da80 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20 69 6e _memory()] is in
2da90 76 6f 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a 2a 20 voked one or.**
2daa0 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 66 72 more times to fr
2dab0 65 65 20 75 70 20 73 6f 6d 65 20 73 70 61 63 65 ee up some space
2dac0 20 62 65 66 6f 72 65 20 74 68 65 20 61 6c 6c 6f before the allo
2dad0 63 61 74 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 cation is perfor
2dae0 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c med..**.** The l
2daf0 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22 imit is called "
2db00 73 6f 66 74 22 2c 20 62 65 63 61 75 73 65 20 69 soft", because i
2db10 66 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 f [sqlite3_relea
2db20 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2a 20 se_memory()].**
2db30 63 61 6e 6e 6f 74 20 66 72 65 65 20 73 75 66 66 cannot free suff
2db40 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f icient memory to
2db50 20 70 72 65 76 65 6e 74 20 74 68 65 20 6c 69 6d prevent the lim
2db60 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 20 65 78 it from being ex
2db70 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d ceeded,.** the m
2db80 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 emory is allocat
2db90 65 64 20 61 6e 79 77 61 79 20 61 6e 64 20 74 68 ed anyway and th
2dba0 65 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 e current operat
2dbb0 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a ion proceeds..**
2dbc0 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20 6f .** A negative o
2dbd0 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 r zero value for
2dbe0 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 N means that th
2dbf0 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20 68 ere is no soft h
2dc00 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a eap limit and.**
2dc10 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 [sqlite3_releas
2dc20 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c e_memory()] will
2dc30 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 only be called
2dc40 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65 when memory is e
2dc50 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 54 68 65 xhausted..** The
2dc60 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 default value f
2dc70 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 or the soft heap
2dc80 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a limit is zero..
2dc90 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b **.** SQLite mak
2dca0 65 73 20 61 20 62 65 73 74 20 65 66 66 6f 72 74 es a best effort
2dcb0 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f to honor the so
2dcc0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 0a 2a ft heap limit..*
2dcd0 2a 20 42 75 74 20 69 66 20 74 68 65 20 73 6f 66 * But if the sof
2dce0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61 6e t heap limit can
2dcf0 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64 2c 20 not be honored,
2dd00 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a execution will.*
2dd10 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f * continue witho
2dd20 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69 ut error or noti
2dd30 66 69 63 61 74 69 6f 6e 2e 20 20 54 68 69 73 20 fication. This
2dd40 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d 69 74 is why the limit
2dd50 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20 61 20 is.** called a
2dd60 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20 49 "soft" limit. I
2dd70 74 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e t is advisory on
2dd80 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 ly..**.** Prior
2dd90 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f to SQLite versio
2dda0 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20 72 6f n 3.5.0, this ro
2ddb0 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73 74 utine only const
2ddc0 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f 72 rained the memor
2ddd0 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 62 y.** allocated b
2dde0 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 y a single threa
2ddf0 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74 68 72 d - the same thr
2de00 65 61 64 20 69 6e 20 77 68 69 63 68 20 74 68 69 ead in which thi
2de10 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75 6e s routine.** run
2de20 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 s. Beginning wi
2de30 74 68 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f th SQLite versio
2de40 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f 66 n 3.5.0, the sof
2de50 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 0a t heap limit is.
2de60 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20 61 6c ** applied to al
2de70 6c 20 74 68 72 65 61 64 73 2e 20 54 68 65 20 76 l threads. The v
2de80 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 20 66 alue specified f
2de90 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 or the soft heap
2dea0 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e 20 limit.** is an
2deb0 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74 upper bound on t
2dec0 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79 20 he total memory
2ded0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 allocation for a
2dee0 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 6e 0a 2a ll threads. In.*
2def0 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 * version 3.5.0
2df00 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 63 68 there is no mech
2df10 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74 69 anism for limiti
2df20 6e 67 20 74 68 65 20 68 65 61 70 20 75 73 61 67 ng the heap usag
2df30 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 64 e for.** individ
2df40 75 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a 0a ual threads..**.
2df50 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
2df60 0a 2a 2a 20 5b 48 31 36 33 35 31 5d 20 5b 48 31 .** [H16351] [H1
2df70 36 33 35 32 5d 20 5b 48 31 36 33 35 33 5d 20 5b 6352] [H16353] [
2df80 48 31 36 33 35 34 5d 20 5b 48 31 36 33 35 35 5d H16354] [H16355]
2df90 20 5b 48 31 36 33 35 38 5d 0a 2a 2f 0a 53 51 4c [H16358].*/.SQL
2dfa0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c ITE_API void sql
2dfb0 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c ite3_soft_heap_l
2dfc0 69 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a imit(int);../*.*
2dfd0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 72 * CAPI3REF: Extr
2dfe0 61 63 74 20 4d 65 74 61 64 61 74 61 20 41 62 6f act Metadata Abo
2dff0 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 ut A Column Of A
2e000 20 54 61 62 6c 65 20 7b 48 31 32 38 35 30 7d 20 Table {H12850}
2e010 3c 53 36 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S60300>.**.** T
2e020 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 his routine retu
2e030 72 6e 73 20 6d 65 74 61 64 61 74 61 20 61 62 6f rns metadata abo
2e040 75 74 20 61 20 73 70 65 63 69 66 69 63 20 63 6f ut a specific co
2e050 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65 63 69 66 lumn of a specif
2e060 69 63 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 74 ic.** database t
2e070 61 62 6c 65 20 61 63 63 65 73 73 69 62 6c 65 20 able accessible
2e080 75 73 69 6e 67 20 74 68 65 20 5b 64 61 74 61 62 using the [datab
2e090 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
2e0a0 68 61 6e 64 6c 65 0a 2a 2a 20 70 61 73 73 65 64 handle.** passed
2e0b0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 66 75 as the first fu
2e0c0 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e nction argument.
2e0d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6c 75 6d .**.** The colum
2e0e0 6e 20 69 73 20 69 64 65 6e 74 69 66 69 65 64 20 n is identified
2e0f0 62 79 20 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 by the second, t
2e100 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 hird and fourth
2e110 70 61 72 61 6d 65 74 65 72 73 20 74 6f 0a 2a 2a parameters to.**
2e120 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 this function.
2e130 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
2e140 65 74 65 72 20 69 73 20 65 69 74 68 65 72 20 74 eter is either t
2e150 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 he name of the d
2e160 61 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e atabase.** (i.e.
2e170 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 20 "main", "temp"
2e180 6f 72 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 or an attached d
2e190 61 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e atabase) contain
2e1a0 69 6e 67 20 74 68 65 20 73 70 65 63 69 66 69 65 ing the specifie
2e1b0 64 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 d.** table or NU
2e1c0 4c 4c 2e 20 49 66 20 69 74 20 69 73 20 4e 55 4c LL. If it is NUL
2e1d0 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 L, then all atta
2e1e0 63 68 65 64 20 64 61 74 61 62 61 73 65 73 20 61 ched databases a
2e1f0 72 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 re searched.** f
2e200 6f 72 20 74 68 65 20 74 61 62 6c 65 20 75 73 69 or the table usi
2e210 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f ng the same algo
2e220 72 69 74 68 6d 20 75 73 65 64 20 62 79 20 74 68 rithm used by th
2e230 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e e database engin
2e240 65 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 e to.** resolve
2e250 75 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c unqualified tabl
2e260 65 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a e references..**
2e270 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e .** The third an
2e280 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 d fourth paramet
2e290 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 ers to this func
2e2a0 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62 tion are the tab
2e2b0 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a le and column.**
2e2c0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73 name of the des
2e2d0 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 ired column, res
2e2e0 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 pectively. Neith
2e2f0 65 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 er of these para
2e300 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62 65 meters.** may be
2e310 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74 NULL..**.** Met
2e320 61 64 61 74 61 20 69 73 20 72 65 74 75 72 6e 65 adata is returne
2e330 64 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20 d by writing to
2e340 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 the memory locat
2e350 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73 20 74 ions passed as t
2e360 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73 75 he 5th.** and su
2e370 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74 bsequent paramet
2e380 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 ers to this func
2e390 74 69 6f 6e 2e 20 41 6e 79 20 6f 66 20 74 68 65 tion. Any of the
2e3a0 73 65 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 se arguments may
2e3b0 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 be.** NULL, in
2e3c0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 63 which case the c
2e3d0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 orresponding ele
2e3e0 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64 61 74 61 ment of metadata
2e3f0 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a is omitted..**.
2e400 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a ** <blockquote>.
2e410 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 ** <table border
2e420 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 ="1">.** <tr><th
2e430 3e 20 50 61 72 61 6d 65 74 65 72 20 3c 74 68 3e > Parameter <th>
2e440 20 4f 75 74 70 75 74 3c 62 72 3e 54 79 70 65 20 Output<br>Type
2e450 3c 74 68 3e 20 20 44 65 73 63 72 69 70 74 69 6f <th> Descriptio
2e460 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e n.**.** <tr><td>
2e470 20 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 5th <td> const
2e480 63 68 61 72 2a 20 3c 74 64 3e 20 44 61 74 61 20 char* <td> Data
2e490 74 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e type.** <tr><td>
2e4a0 20 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 6th <td> const
2e4b0 63 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20 char* <td> Name
2e4c0 6f 66 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 of default colla
2e4d0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a tion sequence.**
2e4e0 20 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74 <tr><td> 7th <t
2e4f0 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c d> int <
2e500 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 td> True if colu
2e510 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c mn has a NOT NUL
2e520 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 L constraint.**
2e530 3c 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64 <tr><td> 8th <td
2e540 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 > int <t
2e550 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d d> True if colum
2e560 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 n is part of the
2e570 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 PRIMARY KEY.**
2e580 3c 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64 <tr><td> 9th <td
2e590 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 > int <t
2e5a0 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d d> True if colum
2e5b0 6e 20 69 73 20 5b 41 55 54 4f 49 4e 43 52 45 4d n is [AUTOINCREM
2e5c0 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e ENT].** </table>
2e5d0 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 .** </blockquote
2e5e0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f >.**.** The memo
2e5f0 72 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 ry pointed to by
2e600 20 74 68 65 20 63 68 61 72 61 63 74 65 72 20 70 the character p
2e610 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 ointers returned
2e620 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64 65 63 6c for the.** decl
2e630 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 aration type and
2e640 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 collation seque
2e650 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c nce is valid onl
2e660 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 y until the next
2e670 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 .** call to any
2e680 53 51 4c 69 74 65 20 41 50 49 20 66 75 6e 63 74 SQLite API funct
2e690 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ion..**.** If th
2e6a0 65 20 73 70 65 63 69 66 69 65 64 20 74 61 62 6c e specified tabl
2e6b0 65 20 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20 e is actually a
2e6c0 76 69 65 77 2c 20 61 6e 20 5b 65 72 72 6f 72 20 view, an [error
2e6d0 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 code] is returne
2e6e0 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 d..**.** If the
2e6f0 73 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e specified column
2e700 20 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 is "rowid", "oi
2e710 64 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 d" or "_rowid_"
2e720 61 6e 64 20 61 6e 0a 2a 2a 20 5b 49 4e 54 45 47 and an.** [INTEG
2e730 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 ER PRIMARY KEY]
2e740 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 column has been
2e750 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 explicitly decla
2e760 72 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 red, then the ou
2e770 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 tput.** paramete
2e780 72 73 20 61 72 65 20 73 65 74 20 66 6f 72 20 74 rs are set for t
2e790 68 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 he explicitly de
2e7a0 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 49 clared column. I
2e7b0 66 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a f there is no.**
2e7c0 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c explicitly decl
2e7d0 61 72 65 64 20 5b 49 4e 54 45 47 45 52 20 50 52 ared [INTEGER PR
2e7e0 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d IMARY KEY] colum
2e7f0 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 n, then the outp
2e800 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 ut.** parameters
2e810 20 61 72 65 20 73 65 74 20 61 73 20 66 6f 6c 6c are set as foll
2e820 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e ows:.**.** <pre>
2e830 0a 2a 2a 20 20 20 20 20 64 61 74 61 20 74 79 70 .** data typ
2e840 65 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20 e: "INTEGER".**
2e850 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 collation se
2e860 71 75 65 6e 63 65 3a 20 22 42 49 4e 41 52 59 22 quence: "BINARY"
2e870 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c .** not null
2e880 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61 : 0.** prima
2e890 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20 ry key: 1.**
2e8a0 20 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a auto increment:
2e8b0 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 0.** </pre>.**.
2e8c0 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e ** This function
2e8d0 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 may load one or
2e8e0 20 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72 more schemas fr
2e8f0 6f 6d 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 om database file
2e900 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f s. If an.** erro
2e910 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 r occurs during
2e920 74 68 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 this process, or
2e930 20 69 66 20 74 68 65 20 72 65 71 75 65 73 74 65 if the requeste
2e940 64 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d d table or colum
2e950 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 n.** cannot be f
2e960 6f 75 6e 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20 ound, an [error
2e970 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 code] is returne
2e980 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d d and an error m
2e990 65 73 73 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69 essage left.** i
2e9a0 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 n the [database
2e9b0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20 connection] (to
2e9c0 62 65 20 72 65 74 72 69 65 76 65 64 20 75 73 69 be retrieved usi
2e9d0 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 ng sqlite3_errms
2e9e0 67 28 29 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 g())..**.** This
2e9f0 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 API is only ava
2ea00 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 ilable if the li
2ea10 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c brary was compil
2ea20 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b ed with the.** [
2ea30 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f SQLITE_ENABLE_CO
2ea40 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 LUMN_METADATA] C
2ea50 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 -preprocessor sy
2ea60 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f mbol defined..*/
2ea70 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
2ea80 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f sqlite3_table_co
2ea90 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20 lumn_metadata(.
2eaa0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
2eab0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
2eac0 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c Connection handl
2ead0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
2eae0 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 r *zDbName,
2eaf0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6e /* Database n
2eb00 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 ame or NULL */.
2eb10 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 const char *zTa
2eb20 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20 bleName, /*
2eb30 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 Table name */.
2eb40 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c const char *zCol
2eb50 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43 umnName, /* C
2eb60 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 olumn name */.
2eb70 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 char const **pzD
2eb80 61 74 61 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f ataType, /* O
2eb90 55 54 50 55 54 3a 20 44 65 63 6c 61 72 65 64 20 UTPUT: Declared
2eba0 64 61 74 61 20 74 79 70 65 20 2a 2f 0a 20 20 63 data type */. c
2ebb0 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f har const **pzCo
2ebc0 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55 llSeq, /* OU
2ebd0 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 TPUT: Collation
2ebe0 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f sequence name */
2ebf0 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c . int *pNotNull
2ec00 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f , /
2ec10 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 * OUTPUT: True i
2ec20 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 f NOT NULL const
2ec30 72 61 69 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a raint exists */.
2ec40 20 20 69 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b int *pPrimaryK
2ec50 65 79 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a ey, /*
2ec60 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 OUTPUT: True if
2ec70 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20 column part of
2ec80 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75 PK */. int *pAu
2ec90 74 6f 69 6e 63 20 20 20 20 20 20 20 20 20 20 20 toinc
2eca0 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 /* OUTPUT: T
2ecb0 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 rue if column is
2ecc0 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 auto-increment
2ecd0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.);../*.** CAP
2ece0 49 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45 I3REF: Load An E
2ecf0 78 74 65 6e 73 69 6f 6e 20 7b 48 31 32 36 30 30 xtension {H12600
2ed00 7d 20 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a } <S20500>.**.**
2ed10 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 This interface
2ed20 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69 74 65 20 loads an SQLite
2ed30 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 extension librar
2ed40 79 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d 65 64 y from the named
2ed50 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 file..**.** {H1
2ed60 32 36 30 31 7d 20 54 68 65 20 73 71 6c 69 74 65 2601} The sqlite
2ed70 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 3_load_extension
2ed80 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 () interface att
2ed90 65 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e empts to load an
2eda0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c .** SQL
2edb0 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 ite extension li
2edc0 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64 20 brary contained
2edd0 69 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 69 6c in the file zFil
2ede0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 32 e..**.** {H12602
2edf0 7d 20 54 68 65 20 65 6e 74 72 79 20 70 6f 69 6e } The entry poin
2ee00 74 20 69 73 20 7a 50 72 6f 63 2e 0a 2a 2a 0a 2a t is zProc..**.*
2ee10 2a 20 7b 48 31 32 36 30 33 7d 20 7a 50 72 6f 63 * {H12603} zProc
2ee20 20 6d 61 79 20 62 65 20 30 2c 20 69 6e 20 77 68 may be 0, in wh
2ee30 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d ich case the nam
2ee40 65 20 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70 e of the entry p
2ee50 6f 69 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 oint.**
2ee60 20 64 65 66 61 75 6c 74 73 20 74 6f 20 22 73 71 defaults to "sq
2ee70 6c 69 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f lite3_extension_
2ee80 69 6e 69 74 22 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 init"..**.** {H1
2ee90 32 36 30 34 7d 20 54 68 65 20 73 71 6c 69 74 65 2604} The sqlite
2eea0 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 3_load_extension
2eeb0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 () interface sha
2eec0 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 ll return.**
2eed0 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b [SQLITE_OK
2eee0 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 ] on success and
2eef0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
2ef00 69 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 if something goe
2ef10 73 20 77 72 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b s wrong..**.** {
2ef20 48 31 32 36 30 35 7d 20 49 66 20 61 6e 20 65 72 H12605} If an er
2ef30 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70 ror occurs and p
2ef40 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 zErrMsg is not 0
2ef50 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 , then the.**
2ef60 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
2ef70 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 load_extension()
2ef80 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c ] interface shal
2ef90 6c 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 l attempt to.**
2efa0 20 20 20 20 20 20 20 20 20 66 69 6c 6c 20 2a 70 fill *p
2efb0 7a 45 72 72 4d 73 67 20 77 69 74 68 20 65 72 72 zErrMsg with err
2efc0 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 or message text
2efd0 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 stored in memory
2efe0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62 74 .** obt
2eff0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 ained from [sqli
2f000 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 7b te3_malloc()]. {
2f010 45 4e 44 7d 20 20 54 68 65 20 63 61 6c 6c 69 6e END} The callin
2f020 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 g function.**
2f030 20 20 20 20 20 20 20 73 68 6f 75 6c 64 20 66 72 should fr
2f040 65 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 20 62 ee this memory b
2f050 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 y calling [sqlit
2f060 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a e3_free()]..**.*
2f070 2a 20 7b 48 31 32 36 30 36 7d 20 45 78 74 65 6e * {H12606} Exten
2f080 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 sion loading mus
2f090 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69 t be enabled usi
2f0a0 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b ng.** [
2f0b0 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c sqlite3_enable_l
2f0c0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d oad_extension()]
2f0d0 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e prior to callin
2f0e0 67 20 74 68 69 73 20 41 50 49 2c 0a 2a 2a 20 20 g this API,.**
2f0f0 20 20 20 20 20 20 20 20 6f 74 68 65 72 77 69 73 otherwis
2f100 65 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 e an error will
2f110 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a be returned..**.
2f120 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 ** See also the
2f130 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 [load_extension(
2f140 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e ) SQL function].
2f150 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
2f160 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f nt sqlite3_load_
2f170 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c extension(. sql
2f180 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
2f190 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65 /* Load the e
2f1a0 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68 xtension into th
2f1b0 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e is database conn
2f1c0 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 ection */. cons
2f1d0 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20 t char *zFile,
2f1e0 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 /* Name of the
2f1f0 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 79 20 shared library
2f200 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e containing exten
2f210 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 sion */. const
2f220 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20 char *zProc,
2f230 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20 /* Entry point.
2f240 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46 Derived from zF
2f250 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68 ile if 0 */. ch
2f260 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20 ar **pzErrMsg
2f270 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72 /* Put error
2f280 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 69 66 message here if
2f290 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a not 0 */.);../*
2f2a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e .** CAPI3REF: En
2f2b0 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 able Or Disable
2f2c0 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e Extension Loadin
2f2d0 67 20 7b 48 31 32 36 32 30 7d 20 3c 53 32 30 35 g {H12620} <S205
2f2e0 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 6f 20 61 73 20 00>.**.** So as
2f2f0 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 not to open secu
2f300 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c rity holes in ol
2f310 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 der applications
2f320 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 that are.** unp
2f330 72 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20 repared to deal
2f340 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c with extension l
2f350 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 oading, and as a
2f360 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c means of disabl
2f370 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e ing.** extension
2f380 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65 loading while e
2f390 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65 valuating user-e
2f3a0 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20 ntered SQL, the
2f3b0 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a following API.**
2f3c0 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 is provided to
2f3d0 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 turn the [sqlite
2f3e0 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 3_load_extension
2f3f0 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e ()] mechanism on
2f400 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 and off..**.**
2f410 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e Extension loadin
2f420 67 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 61 g is off by defa
2f430 75 6c 74 2e 20 53 65 65 20 74 69 63 6b 65 74 20 ult. See ticket
2f440 23 31 38 36 33 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 #1863..**.** {H1
2f450 32 36 32 31 7d 20 43 61 6c 6c 20 74 68 65 20 73 2621} Call the s
2f460 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f qlite3_enable_lo
2f470 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 72 ad_extension() r
2f480 6f 75 74 69 6e 65 20 77 69 74 68 20 6f 6e 6f 66 outine with onof
2f490 66 3d 3d 31 0a 2a 2a 20 20 20 20 20 20 20 20 20 f==1.**
2f4a0 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69 to turn extensi
2f4b0 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 6e on loading on an
2f4c0 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20 6f d call it with o
2f4d0 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e 0a noff==0 to turn.
2f4e0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 74 20 62 ** it b
2f4f0 61 63 6b 20 6f 66 66 20 61 67 61 69 6e 2e 0a 2a ack off again..*
2f500 2a 0a 2a 2a 20 7b 48 31 32 36 32 32 7d 20 45 78 *.** {H12622} Ex
2f510 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 tension loading
2f520 69 73 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c is off by defaul
2f530 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 t..*/.SQLITE_API
2f540 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 int sqlite3_ena
2f550 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 ble_load_extensi
2f560 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 on(sqlite3 *db,
2f570 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a int onoff);../*.
2f580 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 ** CAPI3REF: Aut
2f590 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64 20 omatically Load
2f5a0 41 6e 20 45 78 74 65 6e 73 69 6f 6e 73 20 7b 48 An Extensions {H
2f5b0 31 32 36 34 30 7d 20 3c 53 32 30 35 30 30 3e 0a 12640} <S20500>.
2f5c0 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 63 **.** This API c
2f5d0 61 6e 20 62 65 20 69 6e 76 6f 6b 65 64 20 61 74 an be invoked at
2f5e0 20 70 72 6f 67 72 61 6d 20 73 74 61 72 74 75 70 program startup
2f5f0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 72 65 67 in order to reg
2f600 69 73 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 ister.** one or
2f610 6d 6f 72 65 20 73 74 61 74 69 63 61 6c 6c 79 20 more statically
2f620 6c 69 6e 6b 65 64 20 65 78 74 65 6e 73 69 6f 6e linked extension
2f630 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 61 s that will be a
2f640 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20 61 vailable.** to a
2f650 6c 6c 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 ll new [database
2f660 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 2e 20 7b connections]. {
2f670 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 END}.**.** This
2f680 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61 routine stores a
2f690 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
2f6a0 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 extension in an
2f6b0 61 72 72 61 79 20 74 68 61 74 20 69 73 0a 2a 2a array that is.**
2f6c0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
2f6d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
2f6e0 5d 2e 20 20 49 66 20 79 6f 75 20 72 75 6e 20 61 ]. If you run a
2f6f0 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 20 63 68 65 memory leak che
2f700 63 6b 65 72 0a 2a 2a 20 6f 6e 20 79 6f 75 72 20 cker.** on your
2f710 70 72 6f 67 72 61 6d 20 61 6e 64 20 69 74 20 72 program and it r
2f720 65 70 6f 72 74 73 20 61 20 6c 65 61 6b 20 62 65 eports a leak be
2f730 63 61 75 73 65 20 6f 66 20 74 68 69 73 20 61 72 cause of this ar
2f740 72 61 79 2c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 5b ray, invoke.** [
2f750 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75 sqlite3_reset_au
2f760 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 to_extension()]
2f770 70 72 69 6f 72 20 74 6f 20 73 68 75 74 64 6f 77 prior to shutdow
2f780 6e 20 74 6f 20 66 72 65 65 20 74 68 65 20 6d 65 n to free the me
2f790 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 mory..**.** {H12
2f7a0 36 34 31 7d 20 54 68 69 73 20 66 75 6e 63 74 69 641} This functi
2f7b0 6f 6e 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 on registers an
2f7c0 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79 20 extension entry
2f7d0 70 6f 69 6e 74 20 74 68 61 74 20 69 73 0a 2a 2a point that is.**
2f7e0 20 20 20 20 20 20 20 20 20 20 61 75 74 6f 6d 61 automa
2f7f0 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 20 tically invoked
2f800 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77 20 5b whenever a new [
2f810 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2f820 69 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 ion].**
2f830 20 69 73 20 6f 70 65 6e 65 64 20 75 73 69 6e 67 is opened using
2f840 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
2f850 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ], [sqlite3_open
2f860 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 16()],.**
2f870 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f or [sqlite3_o
2f880 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a pen_v2()]..**.**
2f890 20 7b 48 31 32 36 34 32 7d 20 44 75 70 6c 69 63 {H12642} Duplic
2f8a0 61 74 65 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 ate extensions a
2f8b0 72 65 20 64 65 74 65 63 74 65 64 20 73 6f 20 63 re detected so c
2f8c0 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 alling this rout
2f8d0 69 6e 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ine.**
2f8e0 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77 multiple times w
2f8f0 69 74 68 20 74 68 65 20 73 61 6d 65 20 65 78 74 ith the same ext
2f900 65 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65 ension is harmle
2f910 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34 ss..**.** {H1264
2f920 33 7d 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 3} This routine
2f930 73 74 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 72 stores a pointer
2f940 20 74 6f 20 74 68 65 20 65 78 74 65 6e 73 69 6f to the extensio
2f950 6e 20 69 6e 20 61 6e 20 61 72 72 61 79 0a 2a 2a n in an array.**
2f960 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 69 that i
2f970 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 s obtained from
2f980 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
2f990 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34 )]..**.** {H1264
2f9a0 34 7d 20 41 75 74 6f 6d 61 74 69 63 20 65 78 74 4} Automatic ext
2f9b0 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 61 63 ensions apply ac
2f9c0 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 64 73 ross all threads
2f9d0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
2f9e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 75 74 6f int sqlite3_auto
2f9f0 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 20 _extension(void
2fa00 28 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29 28 76 (*xEntryPoint)(v
2fa10 6f 69 64 29 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 oid));../*.** CA
2fa20 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 75 PI3REF: Reset Au
2fa30 74 6f 6d 61 74 69 63 20 45 78 74 65 6e 73 69 6f tomatic Extensio
2fa40 6e 20 4c 6f 61 64 69 6e 67 20 7b 48 31 32 36 36 n Loading {H1266
2fa50 30 7d 20 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a 0} <S20500>.**.*
2fa60 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 * This function
2fa70 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 70 72 65 disables all pre
2fa80 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 viously register
2fa90 65 64 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 ed automatic.**
2faa0 65 78 74 65 6e 73 69 6f 6e 73 2e 20 7b 45 4e 44 extensions. {END
2fab0 7d 20 20 49 74 20 75 6e 64 6f 65 73 20 74 68 65 } It undoes the
2fac0 20 65 66 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 effect of all p
2fad0 72 69 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 rior.** [sqlite3
2fae0 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 _auto_extension(
2faf0 29 5d 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 )] calls..**.**
2fb00 7b 48 31 32 36 36 31 7d 20 54 68 69 73 20 66 75 {H12661} This fu
2fb10 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 nction disables
2fb20 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72 all previously r
2fb30 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 20 20 20 egistered.**
2fb40 20 20 20 20 20 20 61 75 74 6f 6d 61 74 69 63 20 automatic
2fb50 65 78 74 65 6e 73 69 6f 6e 73 2e 0a 2a 2a 0a 2a extensions..**.*
2fb60 2a 20 7b 48 31 32 36 36 32 7d 20 54 68 69 73 20 * {H12662} This
2fb70 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 function disable
2fb80 73 20 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65 s automatic exte
2fb90 6e 73 69 6f 6e 73 20 69 6e 20 61 6c 6c 20 74 68 nsions in all th
2fba0 72 65 61 64 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 reads..*/.SQLITE
2fbb0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 _API void sqlite
2fbc0 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 3_reset_auto_ext
2fbd0 65 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f ension(void);../
2fbe0 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d *.****** EXPERIM
2fbf0 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 ENTAL - subject
2fc00 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 to change withou
2fc10 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a t notice *******
2fc20 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 *******.**.** Th
2fc30 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 e interface to t
2fc40 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 he virtual-table
2fc50 20 6d 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75 mechanism is cu
2fc60 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 rrently consider
2fc70 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 ed.** to be expe
2fc80 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 rimental. The i
2fc90 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 nterface might c
2fca0 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 hange in incompa
2fcb0 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 tible ways..** I
2fcc0 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 f this is a prob
2fcd0 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 lem for you, do
2fce0 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 not use the inte
2fcf0 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69 rface at this ti
2fd00 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 me..**.** When t
2fd10 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 he virtual-table
2fd20 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 mechanism stabi
2fd30 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 lizes, we will d
2fd40 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e eclare the.** in
2fd50 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 terface fixed, s
2fd60 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 upport it indefi
2fd70 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f nitely, and remo
2fd80 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e ve this comment.
2fd90 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 .*/../*.** Struc
2fda0 74 75 72 65 73 20 75 73 65 64 20 62 79 20 74 68 tures used by th
2fdb0 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 e virtual table
2fdc0 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 interface.*/.typ
2fdd0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
2fde0 74 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33 te3_vtab sqlite3
2fdf0 5f 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73 _vtab;.typedef s
2fe00 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e truct sqlite3_in
2fe10 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 dex_info sqlite3
2fe20 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 _index_info;.typ
2fe30 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
2fe40 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 te3_vtab_cursor
2fe50 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 sqlite3_vtab_cur
2fe60 73 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72 sor;.typedef str
2fe70 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 uct sqlite3_modu
2fe80 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c le sqlite3_modul
2fe90 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 e;../*.** CAPI3R
2fea0 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c EF: Virtual Tabl
2feb0 65 20 4f 62 6a 65 63 74 20 7b 48 31 38 30 30 30 e Object {H18000
2fec0 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 } <S20400>.** KE
2fed0 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f YWORDS: sqlite3_
2fee0 6d 6f 64 75 6c 65 20 7b 76 69 72 74 75 61 6c 20 module {virtual
2fef0 74 61 62 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a table module}.**
2ff00 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a EXPERIMENTAL.**
2ff10 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74 75 .** This structu
2ff20 72 65 2c 20 73 6f 6d 65 74 69 6d 65 73 20 63 61 re, sometimes ca
2ff30 6c 6c 65 64 20 61 20 61 20 22 76 69 72 74 75 61 lled a a "virtua
2ff40 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 22 2c l table module",
2ff50 20 0a 2a 2a 20 64 65 66 69 6e 65 73 20 74 68 65 .** defines the
2ff60 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
2ff70 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 of a [virtual ta
2ff80 62 6c 65 73 5d 2e 20 20 0a 2a 2a 20 54 68 69 73 bles]. .** This
2ff90 20 73 74 72 75 63 74 75 72 65 20 63 6f 6e 73 69 structure consi
2ffa0 73 74 73 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 sts mostly of me
2ffb0 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f thods for the mo
2ffc0 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41 20 76 69 dule..**.** A vi
2ffd0 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 rtual table modu
2ffe0 6c 65 20 69 73 20 63 72 65 61 74 65 64 20 62 79 le is created by
2fff0 20 66 69 6c 6c 69 6e 67 20 69 6e 20 61 20 70 65 filling in a pe
30000 72 73 69 73 74 65 6e 74 0a 2a 2a 20 69 6e 73 74 rsistent.** inst
30010 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 ance of this str
30020 75 63 74 75 72 65 20 61 6e 64 20 70 61 73 73 69 ucture and passi
30030 6e 67 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ng a pointer to
30040 74 68 61 74 20 69 6e 73 74 61 6e 63 65 0a 2a 2a that instance.**
30050 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 to [sqlite3_cre
30060 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6f 72 ate_module()] or
30070 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
30080 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a _module_v2()]..*
30090 2a 20 54 68 65 20 72 65 67 69 73 74 72 61 74 69 * The registrati
300a0 6f 6e 20 72 65 6d 61 69 6e 73 20 76 61 6c 69 64 on remains valid
300b0 20 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65 70 until it is rep
300c0 6c 61 63 65 64 20 62 79 20 61 20 64 69 66 66 65 laced by a diffe
300d0 72 65 6e 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f rent.** module o
300e0 72 20 75 6e 74 69 6c 20 74 68 65 20 5b 64 61 74 r until the [dat
300f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
30100 5d 20 63 6c 6f 73 65 73 2e 20 20 54 68 65 20 63 ] closes. The c
30110 6f 6e 74 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 ontent.** of thi
30120 73 20 73 74 72 75 63 74 75 72 65 20 6d 75 73 74 s structure must
30130 20 6e 6f 74 20 63 68 61 6e 67 65 20 77 68 69 6c not change whil
30140 65 20 69 74 20 69 73 20 72 65 67 69 73 74 65 72 e it is register
30150 65 64 20 77 69 74 68 0a 2a 2a 20 61 6e 79 20 64 ed with.** any d
30160 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
30170 6f 6e 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 on..*/.struct sq
30180 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 lite3_module {.
30190 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 int iVersion;.
301a0 20 69 6e 74 20 28 2a 78 43 72 65 61 74 65 29 28 int (*xCreate)(
301b0 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a sqlite3*, void *
301c0 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 pAux,.
301d0 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 int argc, c
301e0 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 onst char *const
301f0 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 *argv,.
30200 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 sqlite3_vt
30210 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 ab **ppVTab, cha
30220 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 r**);. int (*xC
30230 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 2a onnect)(sqlite3*
30240 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 , void *pAux,.
30250 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 int
30260 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 argc, const cha
30270 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 r *const*argv,.
30280 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71 sq
30290 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 lite3_vtab **ppV
302a0 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 Tab, char**);.
302b0 69 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 65 78 int (*xBestIndex
302c0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a )(sqlite3_vtab *
302d0 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 pVTab, sqlite3_i
302e0 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 ndex_info*);. i
302f0 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 nt (*xDisconnect
30300 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a )(sqlite3_vtab *
30310 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a pVTab);. int (*
30320 78 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65 xDestroy)(sqlite
30330 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 3_vtab *pVTab);.
30340 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 int (*xOpen)(s
30350 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 qlite3_vtab *pVT
30360 61 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 62 ab, sqlite3_vtab
30370 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 _cursor **ppCurs
30380 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c or);. int (*xCl
30390 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 ose)(sqlite3_vta
303a0 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e b_cursor*);. in
303b0 74 20 28 2a 78 46 69 6c 74 65 72 29 28 73 71 6c t (*xFilter)(sql
303c0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 ite3_vtab_cursor
303d0 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 *, int idxNum, c
303e0 6f 6e 73 74 20 63 68 61 72 20 2a 69 64 78 53 74 onst char *idxSt
303f0 72 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 r,.
30400 20 20 20 69 6e 74 20 61 72 67 63 2c 20 73 71 6c int argc, sql
30410 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 ite3_value **arg
30420 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 v);. int (*xNex
30430 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f t)(sqlite3_vtab_
30440 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 cursor*);. int
30450 28 2a 78 45 6f 66 29 28 73 71 6c 69 74 65 33 5f (*xEof)(sqlite3_
30460 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 vtab_cursor*);.
30470 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 int (*xColumn)(
30480 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 sqlite3_vtab_cur
30490 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f sor*, sqlite3_co
304a0 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 ntext*, int);.
304b0 69 6e 74 20 28 2a 78 52 6f 77 69 64 29 28 73 71 int (*xRowid)(sq
304c0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f lite3_vtab_curso
304d0 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 r*, sqlite3_int6
304e0 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 4 *pRowid);. in
304f0 74 20 28 2a 78 55 70 64 61 74 65 29 28 73 71 6c t (*xUpdate)(sql
30500 69 74 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 ite3_vtab *, int
30510 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 , sqlite3_value
30520 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 **, sqlite3_int6
30530 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 4 *);. int (*xB
30540 65 67 69 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 egin)(sqlite3_vt
30550 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e ab *pVTab);. in
30560 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 t (*xSync)(sqlit
30570 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b e3_vtab *pVTab);
30580 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 . int (*xCommit
30590 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a )(sqlite3_vtab *
305a0 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a pVTab);. int (*
305b0 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 xRollback)(sqlit
305c0 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b e3_vtab *pVTab);
305d0 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 . int (*xFindFu
305e0 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f nction)(sqlite3_
305f0 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 vtab *pVtab, int
30600 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 nArg, const cha
30610 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 r *zName,.
30620 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
30630 20 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 void (**pxFunc)
30640 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
30650 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
30660 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 lue**),.
30670 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 v
30680 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a 20 20 oid **ppArg);.
30690 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 int (*xRename)(s
306a0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 qlite3_vtab *pVt
306b0 61 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a ab, const char *
306c0 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a zNew);.};../*.**
306d0 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 CAPI3REF: Virtu
306e0 61 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 69 6e al Table Indexin
306f0 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 7b 48 g Information {H
30700 31 38 31 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a 18100} <S20400>.
30710 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c ** KEYWORDS: sql
30720 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a ite3_index_info.
30730 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a ** EXPERIMENTAL.
30740 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
30750 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 3_index_info str
30760 75 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 73 ucture and its s
30770 75 62 73 74 72 75 63 74 75 72 65 73 20 69 73 20 ubstructures is
30780 75 73 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20 used to.** pass
30790 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f information into
307a0 20 61 6e 64 20 72 65 63 65 69 76 65 20 74 68 65 and receive the
307b0 20 72 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 reply from the
307c0 5b 78 42 65 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 [xBestIndex].**
307d0 6d 65 74 68 6f 64 20 6f 66 20 61 20 5b 76 69 72 method of a [vir
307e0 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c tual table modul
307f0 65 5d 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20 e]. The fields
30800 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a under **Inputs**
30810 20 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 are the.** inpu
30820 74 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78 ts to xBestIndex
30830 20 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e and are read-on
30840 6c 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20 ly. xBestIndex
30850 69 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 inserts its.** r
30860 65 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 esults into the
30870 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c **Outputs** fiel
30880 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43 ds..**.** The aC
30890 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 onstraint[] arra
308a0 79 20 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 y records WHERE
308b0 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e clause constrain
308c0 74 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a ts of the form:.
308d0 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 63 6f 6c 75 6d **.** <pre>colum
308e0 6e 20 4f 50 20 65 78 70 72 3c 2f 70 72 65 3e 0a n OP expr</pre>.
308f0 2a 2a 0a 2a 2a 20 77 68 65 72 65 20 4f 50 20 69 **.** where OP i
30900 73 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d s =, <, <=
30910 2c 20 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d , >, or >=
30920 2e 20 20 54 68 65 20 70 61 72 74 69 63 75 6c 61 . The particula
30930 72 20 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a r operator is.**
30940 20 73 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73 stored in aCons
30950 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e 20 20 54 68 traint[].op. Th
30960 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 e index of the c
30970 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65 64 20 olumn is stored
30980 69 6e 0a 2a 2a 20 61 43 6f 6e 73 74 72 61 69 6e in.** aConstrain
30990 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 20 20 61 43 t[].iColumn. aC
309a0 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 onstraint[].usab
309b0 6c 65 20 69 73 20 54 52 55 45 20 69 66 20 74 68 le is TRUE if th
309c0 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 e.** expr on the
309d0 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 right-hand side
309e0 20 63 61 6e 20 62 65 20 65 76 61 6c 75 61 74 65 can be evaluate
309f0 64 20 28 61 6e 64 20 74 68 75 73 20 74 68 65 20 d (and thus the
30a00 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 constraint.** is
30a10 20 75 73 61 62 6c 65 29 20 61 6e 64 20 66 61 6c usable) and fal
30a20 73 65 20 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e se if it cannot.
30a30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 70 74 69 6d .**.** The optim
30a40 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c izer automatical
30a50 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73 ly inverts terms
30a60 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78 of the form "ex
30a70 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a pr OP column".**
30a80 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 and makes other
30a90 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 simplifications
30aa0 20 74 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c to the WHERE cl
30ab0 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d ause in an attem
30ac0 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 pt to.** get as
30ad0 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73 many WHERE claus
30ae0 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 e terms into the
30af0 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 form shown abov
30b00 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a e as possible..*
30b10 2a 20 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e * The aConstrain
30b20 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20 72 t[] array only r
30b30 65 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c 61 eports WHERE cla
30b40 75 73 65 20 74 65 72 6d 73 20 69 6e 20 74 68 65 use terms in the
30b50 20 63 6f 72 72 65 63 74 0a 2a 2a 20 66 6f 72 6d correct.** form
30b60 20 74 68 61 74 20 72 65 66 65 72 20 74 6f 20 74 that refer to t
30b70 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 76 69 he particular vi
30b80 72 74 75 61 6c 20 74 61 62 6c 65 20 62 65 69 6e rtual table bein
30b90 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a g queried..**.**
30ba0 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f Information abo
30bb0 75 74 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 ut the ORDER BY
30bc0 63 6c 61 75 73 65 20 69 73 20 73 74 6f 72 65 64 clause is stored
30bd0 20 69 6e 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a in aOrderBy[]..
30be0 2a 2a 20 45 61 63 68 20 74 65 72 6d 20 6f 66 20 ** Each term of
30bf0 61 4f 72 64 65 72 42 79 20 72 65 63 6f 72 64 73 aOrderBy records
30c00 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 a column of the
30c10 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 ORDER BY clause
30c20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 78 42 65 ..**.** The [xBe
30c30 73 74 49 6e 64 65 78 5d 20 6d 65 74 68 6f 64 20 stIndex] method
30c40 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73 74 must fill aConst
30c50 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 77 69 74 raintUsage[] wit
30c60 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a h information.**
30c70 20 61 62 6f 75 74 20 77 68 61 74 20 70 61 72 61 about what para
30c80 6d 65 74 65 72 73 20 74 6f 20 70 61 73 73 20 74 meters to pass t
30c90 6f 20 78 46 69 6c 74 65 72 2e 20 20 49 66 20 61 o xFilter. If a
30ca0 72 67 76 49 6e 64 65 78 3e 30 20 74 68 65 6e 0a rgvIndex>0 then.
30cb0 2a 2a 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e ** the right-han
30cc0 64 20 73 69 64 65 20 6f 66 20 74 68 65 20 63 6f d side of the co
30cd0 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f 6e rresponding aCon
30ce0 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 65 76 61 straint[] is eva
30cf0 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62 65 luated.** and be
30d00 63 6f 6d 65 73 20 74 68 65 20 61 72 67 76 49 6e comes the argvIn
30d10 64 65 78 2d 74 68 20 65 6e 74 72 79 20 69 6e 20 dex-th entry in
30d20 61 72 67 76 2e 20 20 49 66 20 61 43 6f 6e 73 74 argv. If aConst
30d30 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d 69 raintUsage[].omi
30d40 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20 74 68 t.** is true, th
30d50 65 6e 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e en the constrain
30d60 74 20 69 73 20 61 73 73 75 6d 65 64 20 74 6f 20 t is assumed to
30d70 62 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65 64 be fully handled
30d80 20 62 79 20 74 68 65 0a 2a 2a 20 76 69 72 74 75 by the.** virtu
30d90 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 69 73 20 al table and is
30da0 6e 6f 74 20 63 68 65 63 6b 65 64 20 61 67 61 69 not checked agai
30db0 6e 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a n by SQLite..**.
30dc0 2a 2a 20 54 68 65 20 69 64 78 4e 75 6d 20 61 6e ** The idxNum an
30dd0 64 20 69 64 78 50 74 72 20 76 61 6c 75 65 73 20 d idxPtr values
30de0 61 72 65 20 72 65 63 6f 72 64 65 64 20 61 6e 64 are recorded and
30df0 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 passed into the
30e00 0a 2a 2a 20 5b 78 46 69 6c 74 65 72 5d 20 6d 65 .** [xFilter] me
30e10 74 68 6f 64 2e 0a 2a 2a 20 5b 73 71 6c 69 74 65 thod..** [sqlite
30e20 33 5f 66 72 65 65 28 29 5d 20 69 73 20 75 73 65 3_free()] is use
30e30 64 20 74 6f 20 66 72 65 65 20 69 64 78 50 74 72 d to free idxPtr
30e40 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 66 if and only iff
30e50 0a 2a 2a 20 6e 65 65 64 54 6f 46 72 65 65 49 64 .** needToFreeId
30e60 78 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a xPtr is true..**
30e70 0a 2a 2a 20 54 68 65 20 6f 72 64 65 72 42 79 43 .** The orderByC
30e80 6f 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 onsumed means th
30e90 61 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 5b at output from [
30ea0 78 46 69 6c 74 65 72 5d 2f 5b 78 4e 65 78 74 5d xFilter]/[xNext]
30eb0 20 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a will occur in.*
30ec0 2a 20 74 68 65 20 63 6f 72 72 65 63 74 20 6f 72 * the correct or
30ed0 64 65 72 20 74 6f 20 73 61 74 69 73 66 79 20 74 der to satisfy t
30ee0 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 he ORDER BY clau
30ef0 73 65 20 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 se so that no se
30f00 70 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e parate.** sortin
30f10 67 20 73 74 65 70 20 69 73 20 72 65 71 75 69 72 g step is requir
30f20 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 73 ed..**.** The es
30f30 74 69 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75 timatedCost valu
30f40 65 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 e is an estimate
30f50 20 6f 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20 of the cost of
30f60 64 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 doing the.** par
30f70 74 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 ticular lookup.
30f80 20 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 A full scan of
30f90 61 20 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65 a table with N e
30fa0 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 ntries should ha
30fb0 76 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 ve.** a cost of
30fc0 4e 2e 20 20 41 20 62 69 6e 61 72 79 20 73 65 61 N. A binary sea
30fd0 72 63 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f rch of a table o
30fe0 66 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 f N entries shou
30ff0 6c 64 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 ld have a.** cos
31000 74 20 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65 t of approximate
31010 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 ly log(N)..*/.st
31020 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 ruct sqlite3_ind
31030 65 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 ex_info {. /* I
31040 6e 70 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e nputs */. int n
31050 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 Constraint;
31060 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 /* Number
31070 6f 66 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43 of entries in aC
31080 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 onstraint */. s
31090 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e truct sqlite3_in
310a0 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b dex_constraint {
310b0 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d . int iColum
310c0 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 n;
310d0 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 /* Column on lef
310e0 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63 t-hand side of c
310f0 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 onstraint */.
31100 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 unsigned char
31110 6f 70 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43 op; /* C
31120 6f 6e 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74 onstraint operat
31130 6f 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 or */. unsig
31140 6e 65 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b ned char usable;
31150 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 /* True if
31160 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 this constraint
31170 69 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 is usable */.
31180 20 20 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 int iTermOffse
31190 74 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 t; /* U
311a0 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d sed internally -
311b0 20 78 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75 xBestIndex shou
311c0 6c 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d ld ignore */. }
311d0 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 *aConstraint;
311e0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54 61 62 /* Tab
311f0 6c 65 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75 le of WHERE clau
31200 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a se constraints *
31210 2f 0a 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 /. int nOrderBy
31220 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f ; /
31230 2a 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d * Number of term
31240 73 20 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42 s in the ORDER B
31250 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 Y clause */. st
31260 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 ruct sqlite3_ind
31270 65 78 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 ex_orderby {.
31280 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 int iColumn;
31290 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 /* C
312a0 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a olumn number */.
312b0 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 unsigned ch
312c0 61 72 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f ar desc; /
312d0 2a 20 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e * True for DESC.
312e0 20 20 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e False for ASC.
312f0 20 2a 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 */. } *aOrderB
31300 79 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 y;
31310 20 2f 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59 /* The ORDER BY
31320 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 clause */. /*
31330 4f 75 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 Outputs */. str
31340 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 uct sqlite3_inde
31350 78 5f 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 x_constraint_usa
31360 67 65 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 ge {. int arg
31370 76 49 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20 vIndex;
31380 20 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 /* if >0, cons
31390 74 72 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f traint is part o
313a0 66 20 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65 f argv to xFilte
313b0 72 20 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 r */. unsigne
313c0 64 20 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 d char omit;
313d0 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 /* Do not code
313e0 20 61 20 74 65 73 74 20 66 6f 72 20 74 68 69 73 a test for this
313f0 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 constraint */.
31400 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 } *aConstraintU
31410 73 61 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e sage;. int idxN
31420 75 6d 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 um;
31430 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 /* Number use
31440 64 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68 d to identify th
31450 65 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 e index */. cha
31460 72 20 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20 r *idxStr;
31470 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e /* Strin
31480 67 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 g, possibly obta
31490 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 ined from sqlite
314a0 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 3_malloc */. in
314b0 74 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53 t needToFreeIdxS
314c0 74 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65 tr; /* Free
314d0 20 69 64 78 53 74 72 20 75 73 69 6e 67 20 73 71 idxStr using sq
314e0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 66 20 lite3_free() if
314f0 74 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 true */. int or
31500 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 derByConsumed;
31510 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 /* True if
31520 6f 75 74 70 75 74 20 69 73 20 61 6c 72 65 61 64 output is alread
31530 79 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 y ordered */. d
31540 6f 75 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43 ouble estimatedC
31550 6f 73 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 ost; /* Est
31560 69 6d 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75 imated cost of u
31570 73 69 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20 sing this index
31580 2a 2f 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51 */.};.#define SQ
31590 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 LITE_INDEX_CONST
315a0 52 41 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 RAINT_EQ 2.#d
315b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 efine SQLITE_IND
315c0 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 EX_CONSTRAINT_GT
315d0 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4.#define SQ
315e0 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 LITE_INDEX_CONST
315f0 52 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 RAINT_LE 8.#d
31600 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 efine SQLITE_IND
31610 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 EX_CONSTRAINT_LT
31620 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 16.#define S
31630 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 QLITE_INDEX_CONS
31640 54 52 41 49 4e 54 5f 47 45 20 20 20 20 33 32 0a TRAINT_GE 32.
31650 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
31660 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f NDEX_CONSTRAINT_
31670 4d 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 MATCH 64../*.**
31680 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 CAPI3REF: Regist
31690 65 72 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 er A Virtual Tab
316a0 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le Implementatio
316b0 6e 20 7b 48 31 38 32 30 30 7d 20 3c 53 32 30 34 n {H18200} <S204
316c0 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 00>.** EXPERIMEN
316d0 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 TAL.**.** This r
316e0 6f 75 74 69 6e 65 20 69 73 20 75 73 65 64 20 74 outine is used t
316f0 6f 20 72 65 67 69 73 74 65 72 20 61 20 6e 65 77 o register a new
31700 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 [virtual table
31710 6d 6f 64 75 6c 65 5d 20 6e 61 6d 65 2e 0a 2a 2a module] name..**
31720 20 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75 Module names mu
31730 73 74 20 62 65 20 72 65 67 69 73 74 65 72 65 64 st be registered
31740 20 62 65 66 6f 72 65 0a 2a 2a 20 63 72 65 61 74 before.** creat
31750 69 6e 67 20 61 20 6e 65 77 20 5b 76 69 72 74 75 ing a new [virtu
31760 61 6c 20 74 61 62 6c 65 5d 20 75 73 69 6e 67 20 al table] using
31770 74 68 65 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 62 the module, or b
31780 65 66 6f 72 65 20 75 73 69 6e 67 20 61 0a 2a 2a efore using a.**
31790 20 70 72 65 65 78 69 73 74 69 6e 67 20 5b 76 69 preexisting [vi
317a0 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 66 6f 72 rtual table] for
317b0 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a the module..**.
317c0 2a 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 6e 61 ** The module na
317d0 6d 65 20 69 73 20 72 65 67 69 73 74 65 72 65 64 me is registered
317e0 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 on the [databas
317f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 e connection] sp
31800 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 ecified.** by th
31810 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
31820 72 2e 20 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 r. The name of
31830 74 68 65 20 6d 6f 64 75 6c 65 20 69 73 20 67 69 the module is gi
31840 76 65 6e 20 62 79 20 74 68 65 20 0a 2a 2a 20 73 ven by the .** s
31850 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e econd parameter.
31860 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 The third para
31870 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 meter is a point
31880 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 69 6d 70 er to.** the imp
31890 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 lementation of t
318a0 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c he [virtual tabl
318b0 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 20 54 68 65 e module]. The
318c0 20 66 6f 75 72 74 68 0a 2a 2a 20 70 61 72 61 6d fourth.** param
318d0 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 eter is an arbit
318e0 72 61 72 79 20 63 6c 69 65 6e 74 20 64 61 74 61 rary client data
318f0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 pointer that is
31900 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 0a passed through.
31910 2a 2a 20 69 6e 74 6f 20 74 68 65 20 5b 78 43 72 ** into the [xCr
31920 65 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e eate] and [xConn
31930 65 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 ect] methods of
31940 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c the virtual tabl
31950 65 20 6d 6f 64 75 6c 65 0a 2a 2a 20 77 68 65 6e e module.** when
31960 20 61 20 6e 65 77 20 76 69 72 74 75 61 6c 20 74 a new virtual t
31970 61 62 6c 65 20 69 73 20 62 65 20 62 65 69 6e 67 able is be being
31980 20 63 72 65 61 74 65 64 20 6f 72 20 72 65 69 6e created or rein
31990 69 74 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a itialized..**.**
319a0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 This interface
319b0 68 61 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 has exactly the
319c0 73 61 6d 65 20 65 66 66 65 63 74 20 61 73 20 63 same effect as c
319d0 61 6c 6c 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 alling.** [sqlit
319e0 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 e3_create_module
319f0 5f 76 32 28 29 5d 20 77 69 74 68 20 61 20 4e 55 _v2()] with a NU
31a00 4c 4c 20 63 6c 69 65 6e 74 20 64 61 74 61 20 64 LL client data d
31a10 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2f 0a 53 51 estructor..*/.SQ
31a20 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
31a30 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 EXPERIMENTAL int
31a40 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
31a50 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69 74 65 module(. sqlite
31a60 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
31a70 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 /* SQLite c
31a80 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 onnection to reg
31a90 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 ister module wit
31aa0 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 h */. const cha
31ab0 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 r *zName,
31ac0 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 /* Name of the
31ad0 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e module */. con
31ae0 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c st sqlite3_modul
31af0 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 68 6f e *p, /* Metho
31b00 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c ds for the modul
31b10 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 43 6c e */. void *pCl
31b20 69 65 6e 74 44 61 74 61 20 20 20 20 20 20 20 20 ientData
31b30 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 /* Client data
31b40 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f for xCreate/xCo
31b50 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a nnect */.);../*.
31b60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 ** CAPI3REF: Reg
31b70 69 73 74 65 72 20 41 20 56 69 72 74 75 61 6c 20 ister A Virtual
31b80 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61 Table Implementa
31b90 74 69 6f 6e 20 7b 48 31 38 32 31 30 7d 20 3c 53 tion {H18210} <S
31ba0 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 20400>.** EXPERI
31bb0 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 MENTAL.**.** Thi
31bc0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 64 65 s routine is ide
31bd0 6e 74 69 63 61 6c 20 74 6f 20 74 68 65 20 5b 73 ntical to the [s
31be0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f qlite3_create_mo
31bf0 64 75 6c 65 28 29 5d 20 6d 65 74 68 6f 64 2c 0a dule()] method,.
31c00 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 ** except that i
31c10 74 20 68 61 73 20 61 6e 20 65 78 74 72 61 20 70 t has an extra p
31c20 61 72 61 6d 65 74 65 72 20 74 6f 20 73 70 65 63 arameter to spec
31c30 69 66 79 20 0a 2a 2a 20 61 20 64 65 73 74 72 75 ify .** a destru
31c40 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 66 6f ctor function fo
31c50 72 20 74 68 65 20 63 6c 69 65 6e 74 20 64 61 74 r the client dat
31c60 61 20 70 6f 69 6e 74 65 72 2e 20 20 53 51 4c 69 a pointer. SQLi
31c70 74 65 20 77 69 6c 6c 0a 2a 2a 20 69 6e 76 6f 6b te will.** invok
31c80 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 e the destructor
31c90 20 66 75 6e 63 74 69 6f 6e 20 28 69 66 20 69 74 function (if it
31ca0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 77 68 is not NULL) wh
31cb0 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 6e 6f 20 en SQLite.** no
31cc0 6c 6f 6e 67 65 72 20 6e 65 65 64 73 20 74 68 65 longer needs the
31cd0 20 70 43 6c 69 65 6e 74 44 61 74 61 20 70 6f 69 pClientData poi
31ce0 6e 74 65 72 2e 20 20 0a 2a 2f 0a 53 51 4c 49 54 nter. .*/.SQLIT
31cf0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 E_API SQLITE_EXP
31d00 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 ERIMENTAL int sq
31d10 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 lite3_create_mod
31d20 75 6c 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 ule_v2(. sqlite
31d30 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
31d40 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 /* SQLite c
31d50 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 onnection to reg
31d60 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 ister module wit
31d70 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 h */. const cha
31d80 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 r *zName,
31d90 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 /* Name of the
31da0 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e module */. con
31db0 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c st sqlite3_modul
31dc0 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 68 6f e *p, /* Metho
31dd0 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c ds for the modul
31de0 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 43 6c e */. void *pCl
31df0 69 65 6e 74 44 61 74 61 2c 20 20 20 20 20 20 20 ientData,
31e00 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 /* Client data
31e10 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f for xCreate/xCo
31e20 6e 6e 65 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28 nnect */. void(
31e30 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a *xDestroy)(void*
31e40 29 20 20 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 ) /* Module
31e50 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 destructor funct
31e60 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a ion */.);../*.**
31e70 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 CAPI3REF: Virtu
31e80 61 6c 20 54 61 62 6c 65 20 49 6e 73 74 61 6e 63 al Table Instanc
31e90 65 20 4f 62 6a 65 63 74 20 7b 48 31 38 30 31 30 e Object {H18010
31ea0 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 } <S20400>.** KE
31eb0 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f YWORDS: sqlite3_
31ec0 76 74 61 62 0a 2a 2a 20 45 58 50 45 52 49 4d 45 vtab.** EXPERIME
31ed0 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 NTAL.**.** Every
31ee0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 [virtual table
31ef0 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e module] implemen
31f00 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 tation uses a su
31f10 62 63 6c 61 73 73 0a 2a 2a 20 6f 66 20 74 68 65 bclass.** of the
31f20 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 following struc
31f30 74 75 72 65 20 74 6f 20 64 65 73 63 72 69 62 65 ture to describe
31f40 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 69 6e a particular in
31f50 73 74 61 6e 63 65 0a 2a 2a 20 6f 66 20 74 68 65 stance.** of the
31f60 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d [virtual table]
31f70 2e 20 20 45 61 63 68 20 73 75 62 63 6c 61 73 73 . Each subclass
31f80 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 69 6c will.** be tail
31f90 6f 72 65 64 20 74 6f 20 74 68 65 20 73 70 65 63 ored to the spec
31fa0 69 66 69 63 20 6e 65 65 64 73 20 6f 66 20 74 68 ific needs of th
31fb0 65 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 e module impleme
31fc0 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 ntation..** The
31fd0 70 75 72 70 6f 73 65 20 6f 66 20 74 68 69 73 20 purpose of this
31fe0 73 75 70 65 72 63 6c 61 73 73 20 69 73 20 74 6f superclass is to
31ff0 20 64 65 66 69 6e 65 20 63 65 72 74 61 69 6e 20 define certain
32000 66 69 65 6c 64 73 20 74 68 61 74 20 61 72 65 0a fields that are.
32010 2a 2a 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c ** common to all
32020 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e module implemen
32030 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 56 tations..**.** V
32040 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6d 65 irtual tables me
32050 74 68 6f 64 73 20 63 61 6e 20 73 65 74 20 61 6e thods can set an
32060 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 62 error message b
32070 79 20 61 73 73 69 67 6e 69 6e 67 20 61 0a 2a 2a y assigning a.**
32080 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 string obtained
32090 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
320a0 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 7a 45 72 printf()] to zEr
320b0 72 4d 73 67 2e 20 20 54 68 65 20 6d 65 74 68 6f rMsg. The metho
320c0 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 d should.** take
320d0 20 63 61 72 65 20 74 68 61 74 20 61 6e 79 20 70 care that any p
320e0 72 69 6f 72 20 73 74 72 69 6e 67 20 69 73 20 66 rior string is f
320f0 72 65 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 reed by a call t
32100 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 o [sqlite3_free(
32110 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 )].** prior to a
32120 73 73 69 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 ssigning a new s
32130 74 72 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 tring to zErrMsg
32140 2e 20 20 41 66 74 65 72 20 74 68 65 20 65 72 72 . After the err
32150 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 or message.** is
32160 20 64 65 6c 69 76 65 72 65 64 20 75 70 20 74 6f delivered up to
32170 20 74 68 65 20 63 6c 69 65 6e 74 20 61 70 70 6c the client appl
32180 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 ication, the str
32190 69 6e 67 20 77 69 6c 6c 20 62 65 20 61 75 74 6f ing will be auto
321a0 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 matically.** fre
321b0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 66 72 ed by sqlite3_fr
321c0 65 65 28 29 20 61 6e 64 20 74 68 65 20 7a 45 72 ee() and the zEr
321d0 72 4d 73 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 rMsg field will
321e0 62 65 20 7a 65 72 6f 65 64 2e 0a 2a 2f 0a 73 74 be zeroed..*/.st
321f0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 ruct sqlite3_vta
32200 62 20 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 b {. const sqli
32210 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64 te3_module *pMod
32220 75 6c 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f 64 ule; /* The mod
32230 75 6c 65 20 66 6f 72 20 74 68 69 73 20 76 69 72 ule for this vir
32240 74 75 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 20 tual table */.
32250 69 6e 74 20 6e 52 65 66 3b 20 20 20 20 20 20 20 int nRef;
32260 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
32270 2f 2a 20 4e 4f 20 4c 4f 4e 47 45 52 20 55 53 45 /* NO LONGER USE
32280 44 20 2a 2f 0a 20 20 63 68 61 72 20 2a 7a 45 72 D */. char *zEr
32290 72 4d 73 67 3b 20 20 20 20 20 20 20 20 20 20 20 rMsg;
322a0 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 /* Error
322b0 6d 65 73 73 61 67 65 20 66 72 6f 6d 20 73 71 6c message from sql
322c0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 2a ite3_mprintf() *
322d0 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 /. /* Virtual t
322e0 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 able implementat
322f0 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 ions will typica
32300 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e lly add addition
32310 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a al fields */.};.
32320 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
32330 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 43 Virtual Table C
32340 75 72 73 6f 72 20 4f 62 6a 65 63 74 20 20 7b 48 ursor Object {H
32350 31 38 30 32 30 7d 20 3c 53 32 30 34 30 30 3e 0a 18020} <S20400>.
32360 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c ** KEYWORDS: sql
32370 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 ite3_vtab_cursor
32380 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 {virtual table
32390 63 75 72 73 6f 72 7d 0a 2a 2a 20 45 58 50 45 52 cursor}.** EXPER
323a0 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 45 76 IMENTAL.**.** Ev
323b0 65 72 79 20 5b 76 69 72 74 75 61 6c 20 74 61 62 ery [virtual tab
323c0 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 le module] imple
323d0 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 mentation uses a
323e0 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 subclass of the
323f0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 .** following st
32400 72 75 63 74 75 72 65 20 74 6f 20 64 65 73 63 72 ructure to descr
32410 69 62 65 20 63 75 72 73 6f 72 73 20 74 68 61 74 ibe cursors that
32420 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74 68 65 0a point into the.
32430 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c ** [virtual tabl
32440 65 5d 20 61 6e 64 20 61 72 65 20 75 73 65 64 0a e] and are used.
32450 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74 68 72 6f 75 ** to loop throu
32460 67 68 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 gh the virtual t
32470 61 62 6c 65 2e 20 20 43 75 72 73 6f 72 73 20 61 able. Cursors a
32480 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 re created using
32490 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
324a0 5f 6d 6f 64 75 6c 65 2e 78 4f 70 65 6e 20 7c 20 _module.xOpen |
324b0 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 xOpen] method of
324c0 20 74 68 65 20 6d 6f 64 75 6c 65 20 61 6e 64 20 the module and
324d0 61 72 65 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a are destroyed.**
324e0 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 by the [sqlite3
324f0 5f 6d 6f 64 75 6c 65 2e 78 43 6c 6f 73 65 20 7c _module.xClose |
32500 20 78 43 6c 6f 73 65 5d 20 6d 65 74 68 6f 64 2e xClose] method.
32510 20 20 43 75 73 73 6f 72 73 20 61 72 65 20 75 73 Cussors are us
32520 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 78 46 ed.** by the [xF
32530 69 6c 74 65 72 5d 2c 20 5b 78 4e 65 78 74 5d 2c ilter], [xNext],
32540 20 5b 78 45 6f 66 5d 2c 20 5b 78 43 6f 6c 75 6d [xEof], [xColum
32550 6e 5d 2c 20 61 6e 64 20 5b 78 52 6f 77 69 64 5d n], and [xRowid]
32560 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 74 methods.** of t
32570 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 he module. Each
32580 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e module implemen
32590 74 61 74 69 6f 6e 20 77 69 6c 6c 20 64 65 66 69 tation will defi
325a0 6e 65 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e ne.** the conten
325b0 74 20 6f 66 20 61 20 63 75 72 73 6f 72 20 73 74 t of a cursor st
325c0 72 75 63 74 75 72 65 20 74 6f 20 73 75 69 74 20 ructure to suit
325d0 69 74 73 20 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a its own needs..*
325e0 2a 0a 2a 2a 20 54 68 69 73 20 73 75 70 65 72 63 *.** This superc
325f0 6c 61 73 73 20 65 78 69 73 74 73 20 69 6e 20 6f lass exists in o
32600 72 64 65 72 20 74 6f 20 64 65 66 69 6e 65 20 66 rder to define f
32610 69 65 6c 64 73 20 6f 66 20 74 68 65 20 63 75 72 ields of the cur
32620 73 6f 72 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 sor that.** are
32630 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d common to all im
32640 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a plementations..*
32650 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 /.struct sqlite3
32660 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20 _vtab_cursor {.
32670 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 sqlite3_vtab *p
32680 56 74 61 62 3b 20 20 20 20 20 20 2f 2a 20 56 69 Vtab; /* Vi
32690 72 74 75 61 6c 20 74 61 62 6c 65 20 6f 66 20 74 rtual table of t
326a0 68 69 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20 his cursor */.
326b0 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 /* Virtual table
326c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
326d0 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 will typically
326e0 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 add additional f
326f0 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a ields */.};../*.
32700 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 ** CAPI3REF: Dec
32710 6c 61 72 65 20 54 68 65 20 53 63 68 65 6d 61 20 lare The Schema
32720 4f 66 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 Of A Virtual Tab
32730 6c 65 20 7b 48 31 38 32 38 30 7d 20 3c 53 32 30 le {H18280} <S20
32740 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 400>.** EXPERIME
32750 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b NTAL.**.** The [
32760 78 43 72 65 61 74 65 5d 20 61 6e 64 20 5b 78 43 xCreate] and [xC
32770 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73 20 onnect] methods
32780 6f 66 20 61 0a 2a 2a 20 5b 76 69 72 74 75 61 6c of a.** [virtual
32790 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 63 table module] c
327a0 61 6c 6c 20 74 68 69 73 20 69 6e 74 65 72 66 61 all this interfa
327b0 63 65 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72 65 ce.** to declare
327c0 20 74 68 65 20 66 6f 72 6d 61 74 20 28 74 68 65 the format (the
327d0 20 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 61 74 names and datat
327e0 79 70 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 ypes of the colu
327f0 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20 76 mns) of.** the v
32800 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 74 68 irtual tables th
32810 65 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f ey implement..*/
32820 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 .SQLITE_API SQLI
32830 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 TE_EXPERIMENTAL
32840 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 65 63 6c int sqlite3_decl
32850 61 72 65 5f 76 74 61 62 28 73 71 6c 69 74 65 33 are_vtab(sqlite3
32860 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
32870 53 51 4c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 SQL);../*.** CAP
32880 49 33 52 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20 I3REF: Overload
32890 41 20 46 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41 A Function For A
328a0 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 7b Virtual Table {
328b0 48 31 38 33 30 30 7d 20 3c 53 32 30 34 30 30 3e H18300} <S20400>
328c0 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c .** EXPERIMENTAL
328d0 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 .**.** Virtual t
328e0 61 62 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64 ables can provid
328f0 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d e alternative im
32900 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 plementations of
32910 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 functions.** us
32920 69 6e 67 20 74 68 65 20 5b 78 46 69 6e 64 46 75 ing the [xFindFu
32930 6e 63 74 69 6f 6e 5d 20 6d 65 74 68 6f 64 20 6f nction] method o
32940 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 f the [virtual t
32950 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 0a able module]. .
32960 2a 2a 20 42 75 74 20 67 6c 6f 62 61 6c 20 76 65 ** But global ve
32970 72 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20 rsions of those
32980 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 functions.** mus
32990 74 20 65 78 69 73 74 20 69 6e 20 6f 72 64 65 72 t exist in order
329a0 20 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 to be overloade
329b0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 d..**.** This AP
329c0 49 20 6d 61 6b 65 73 20 73 75 72 65 20 61 20 67 I makes sure a g
329d0 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f 66 lobal version of
329e0 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 a function with
329f0 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a a particular.**
32a00 20 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65 72 name and number
32a10 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20 65 of parameters e
32a20 78 69 73 74 73 2e 20 20 49 66 20 6e 6f 20 73 75 xists. If no su
32a30 63 68 20 66 75 6e 63 74 69 6f 6e 20 65 78 69 73 ch function exis
32a40 74 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 69 ts.** before thi
32a50 73 20 41 50 49 20 69 73 20 63 61 6c 6c 65 64 2c s API is called,
32a60 20 61 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 a new function
32a70 69 73 20 63 72 65 61 74 65 64 2e 20 20 54 68 65 is created. The
32a80 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a implementation.
32a90 2a 2a 20 6f 66 20 74 68 65 20 6e 65 77 20 66 75 ** of the new fu
32aa0 6e 63 74 69 6f 6e 20 61 6c 77 61 79 73 20 63 61 nction always ca
32ab0 75 73 65 73 20 61 6e 20 65 78 63 65 70 74 69 6f uses an exceptio
32ac0 6e 20 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20 n to be thrown.
32ad0 20 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66 So.** the new f
32ae0 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 unction is not g
32af0 6f 6f 64 20 66 6f 72 20 61 6e 79 74 68 69 6e 67 ood for anything
32b00 20 62 79 20 69 74 73 65 6c 66 2e 20 20 49 74 73 by itself. Its
32b10 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65 only.** purpose
32b20 20 69 73 20 74 6f 20 62 65 20 61 20 70 6c 61 63 is to be a plac
32b30 65 68 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e eholder function
32b40 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 that can be ove
32b50 72 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20 61 20 rloaded.** by a
32b60 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e [virtual table].
32b70 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 .*/.SQLITE_API S
32b80 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 QLITE_EXPERIMENT
32b90 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f AL int sqlite3_o
32ba0 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e verload_function
32bb0 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 (sqlite3*, const
32bc0 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 char *zFuncName
32bd0 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a , int nArg);../*
32be0 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 .** The interfac
32bf0 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c e to the virtual
32c00 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d -table mechanism
32c10 20 64 65 66 69 6e 65 64 20 61 62 6f 76 65 20 28 defined above (
32c20 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20 back up.** to a
32c30 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62 comment remarkab
32c40 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 ly similar to th
32c50 69 73 20 6f 6e 65 29 20 69 73 20 63 75 72 72 65 is one) is curre
32c60 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a ntly considered.
32c70 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d ** to be experim
32c80 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 ental. The inte
32c90 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e rface might chan
32ca0 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 ge in incompatib
32cb0 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 le ways..** If t
32cc0 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d his is a problem
32cd0 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 for you, do not
32ce0 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 use the interfa
32cf0 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e ce at this time.
32d00 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 .**.** When the
32d10 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 virtual-table me
32d20 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a chanism stabiliz
32d30 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c es, we will decl
32d40 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 are the.** inter
32d50 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 face fixed, supp
32d60 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 ort it indefinit
32d70 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 ely, and remove
32d80 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a this comment..**
32d90 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 .****** EXPERIME
32da0 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 NTAL - subject t
32db0 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 o change without
32dc0 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a notice ********
32dd0 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a ******.*/../*.**
32de0 20 43 41 50 49 33 52 45 46 3a 20 41 20 48 61 6e CAPI3REF: A Han
32df0 64 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e 20 42 dle To An Open B
32e00 4c 4f 42 20 7b 48 31 37 38 30 30 7d 20 3c 53 33 LOB {H17800} <S3
32e10 30 32 33 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 0230>.** KEYWORD
32e20 53 3a 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 7d S: {BLOB handle}
32e30 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 7d 0a {BLOB handles}.
32e40 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 **.** An instanc
32e50 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 e of this object
32e60 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f represents an o
32e70 70 65 6e 20 42 4c 4f 42 20 6f 6e 20 77 68 69 63 pen BLOB on whic
32e80 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c h.** [sqlite3_bl
32e90 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d ob_open | increm
32ea0 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 ental BLOB I/O]
32eb0 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 can be performed
32ec0 2e 0a 2a 2a 20 4f 62 6a 65 63 74 73 20 6f 66 20 ..** Objects of
32ed0 74 68 69 73 20 74 79 70 65 20 61 72 65 20 63 72 this type are cr
32ee0 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 eated by [sqlite
32ef0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a 3_blob_open()].*
32f00 2a 20 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20 * and destroyed
32f10 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 by [sqlite3_blob
32f20 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 54 68 _close()]..** Th
32f30 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f e [sqlite3_blob_
32f40 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c read()] and [sql
32f50 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 ite3_blob_write(
32f60 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a )] interfaces.**
32f70 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
32f80 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 73 6d read or write sm
32f90 61 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e 73 20 all subsections
32fa0 6f 66 20 74 68 65 20 42 4c 4f 42 2e 0a 2a 2a 20 of the BLOB..**
32fb0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f The [sqlite3_blo
32fc0 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 b_bytes()] inter
32fd0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 face returns the
32fe0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f size of the BLO
32ff0 42 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a 74 B in bytes..*/.t
33000 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
33010 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c 69 74 lite3_blob sqlit
33020 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 e3_blob;../*.**
33030 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 20 41 CAPI3REF: Open A
33040 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72 65 6d BLOB For Increm
33050 65 6e 74 61 6c 20 49 2f 4f 20 7b 48 31 37 38 31 ental I/O {H1781
33060 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 0} <S30230>.**.*
33070 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 * This interface
33080 73 20 6f 70 65 6e 73 20 61 20 5b 42 4c 4f 42 20 s opens a [BLOB
33090 68 61 6e 64 6c 65 20 7c 20 68 61 6e 64 6c 65 5d handle | handle]
330a0 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 6c 6f 63 to the BLOB loc
330b0 61 74 65 64 0a 2a 2a 20 69 6e 20 72 6f 77 20 69 ated.** in row i
330c0 52 6f 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c Row, column zCol
330d0 75 6d 6e 2c 20 74 61 62 6c 65 20 7a 54 61 62 6c umn, table zTabl
330e0 65 20 69 6e 20 64 61 74 61 62 61 73 65 20 7a 44 e in database zD
330f0 62 3b 0a 2a 2a 20 69 6e 20 6f 74 68 65 72 20 77 b;.** in other w
33100 6f 72 64 73 2c 20 74 68 65 20 73 61 6d 65 20 42 ords, the same B
33110 4c 4f 42 20 74 68 61 74 20 77 6f 75 6c 64 20 62 LOB that would b
33120 65 20 73 65 6c 65 63 74 65 64 20 62 79 3a 0a 2a e selected by:.*
33130 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 *.** <pre>.**
33140 20 20 53 45 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e SELECT zColumn
33150 20 46 52 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 FROM zDb.zTable
33160 20 57 48 45 52 45 20 5b 72 6f 77 69 64 5d 20 3d WHERE [rowid] =
33170 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e iRow;.** </pre>
33180 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 {END}.**.** If
33190 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 the flags parame
331a0 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c ter is non-zero,
331b0 20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69 then the BLOB i
331c0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 s opened for rea
331d0 64 0a 2a 2a 20 61 6e 64 20 77 72 69 74 65 20 61 d.** and write a
331e0 63 63 65 73 73 2e 20 49 66 20 69 74 20 69 73 20 ccess. If it is
331f0 7a 65 72 6f 2c 20 74 68 65 20 42 4c 4f 42 20 69 zero, the BLOB i
33200 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 s opened for rea
33210 64 20 61 63 63 65 73 73 2e 0a 2a 2a 20 49 74 20 d access..** It
33220 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 is not possible
33230 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c 75 6d 6e to open a column
33240 20 74 68 61 74 20 69 73 20 70 61 72 74 20 6f 66 that is part of
33250 20 61 6e 20 69 6e 64 65 78 20 6f 72 20 70 72 69 an index or pri
33260 6d 61 72 79 20 0a 2a 2a 20 6b 65 79 20 66 6f 72 mary .** key for
33270 20 77 72 69 74 69 6e 67 2e 20 5e 49 66 20 5b 66 writing. ^If [f
33280 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 oreign key const
33290 72 61 69 6e 74 73 5d 20 61 72 65 20 65 6e 61 62 raints] are enab
332a0 6c 65 64 2c 20 69 74 20 69 73 20 0a 2a 2a 20 6e led, it is .** n
332b0 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 6f ot possible to o
332c0 70 65 6e 20 61 20 63 6f 6c 75 6d 6e 20 74 68 61 pen a column tha
332d0 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 20 5b t is part of a [
332e0 63 68 69 6c 64 20 6b 65 79 5d 20 66 6f 72 20 77 child key] for w
332f0 72 69 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 4e 6f riting..**.** No
33300 74 65 20 74 68 61 74 20 74 68 65 20 64 61 74 61 te that the data
33310 62 61 73 65 20 6e 61 6d 65 20 69 73 20 6e 6f 74 base name is not
33320 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 74 68 the filename th
33330 61 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 at contains.** t
33340 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74 20 he database but
33350 72 61 74 68 65 72 20 74 68 65 20 73 79 6d 62 6f rather the symbo
33360 6c 69 63 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 lic name of the
33370 64 61 74 61 62 61 73 65 20 74 68 61 74 0a 2a 2a database that.**
33380 20 69 73 20 61 73 73 69 67 6e 65 64 20 77 68 65 is assigned whe
33390 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 n the database i
333a0 73 20 63 6f 6e 6e 65 63 74 65 64 20 75 73 69 6e s connected usin
333b0 67 20 5b 41 54 54 41 43 48 5d 2e 0a 2a 2a 20 46 g [ATTACH]..** F
333c0 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 or the main data
333d0 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65 20 64 base file, the d
333e0 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 atabase name is
333f0 22 6d 61 69 6e 22 2e 0a 2a 2a 20 46 6f 72 20 54 "main"..** For T
33400 45 4d 50 20 74 61 62 6c 65 73 2c 20 74 68 65 20 EMP tables, the
33410 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 database name is
33420 20 22 74 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20 4f "temp"..**.** O
33430 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 n success, [SQLI
33440 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e TE_OK] is return
33450 65 64 20 61 6e 64 20 74 68 65 20 6e 65 77 20 5b ed and the new [
33460 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 73 20 BLOB handle] is
33470 77 72 69 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70 written.** to *p
33480 70 42 6c 6f 62 2e 20 4f 74 68 65 72 77 69 73 65 pBlob. Otherwise
33490 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d an [error code]
334a0 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 is returned and
334b0 20 2a 70 70 42 6c 6f 62 20 69 73 20 73 65 74 0a *ppBlob is set.
334c0 2a 2a 20 74 6f 20 62 65 20 61 20 6e 75 6c 6c 20 ** to be a null
334d0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68 69 73 pointer..** This
334e0 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 74 function sets t
334f0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
33500 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72 20 63 nection] error c
33510 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 0a ode and message.
33520 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 ** accessible vi
33530 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f a [sqlite3_errco
33540 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 de()] and [sqlit
33550 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 e3_errmsg()] and
33560 20 72 65 6c 61 74 65 64 0a 2a 2a 20 66 75 6e 63 related.** func
33570 74 69 6f 6e 73 2e 20 20 4e 6f 74 65 20 74 68 61 tions. Note tha
33580 74 20 74 68 65 20 2a 70 70 42 6c 6f 62 20 76 61 t the *ppBlob va
33590 72 69 61 62 6c 65 20 69 73 20 61 6c 77 61 79 73 riable is always
335a0 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 69 6e 20 initialized in
335b0 61 0a 2a 2a 20 77 61 79 20 74 68 61 74 20 6d 61 a.** way that ma
335c0 6b 65 73 20 69 74 20 73 61 66 65 20 74 6f 20 69 kes it safe to i
335d0 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 62 nvoke [sqlite3_b
335e0 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 20 6f 6e 20 lob_close()] on
335f0 2a 70 70 42 6c 6f 62 0a 2a 2a 20 72 65 67 61 72 *ppBlob.** regar
33600 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 dless of the suc
33610 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 20 cess or failure
33620 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e of this routine.
33630 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 6f .**.** If the ro
33640 77 20 74 68 61 74 20 61 20 42 4c 4f 42 20 68 61 w that a BLOB ha
33650 6e 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 ndle points to i
33660 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 61 6e s modified by an
33670 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20 5b 44 .** [UPDATE], [D
33680 45 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20 5b 4f ELETE], or by [O
33690 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69 64 65 N CONFLICT] side
336a0 2d 65 66 66 65 63 74 73 0a 2a 2a 20 74 68 65 6e -effects.** then
336b0 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 the BLOB handle
336c0 20 69 73 20 6d 61 72 6b 65 64 20 61 73 20 22 65 is marked as "e
336d0 78 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68 69 73 xpired"..** This
336e0 20 69 73 20 74 72 75 65 20 69 66 20 61 6e 79 20 is true if any
336f0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 6f column of the ro
33700 77 20 69 73 20 63 68 61 6e 67 65 64 2c 20 65 76 w is changed, ev
33710 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6f en a column.** o
33720 74 68 65 72 20 74 68 61 6e 20 74 68 65 20 6f 6e ther than the on
33730 65 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c e the BLOB handl
33740 65 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 0a 2a 2a e is open on..**
33750 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 Calls to [sqlit
33760 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 e3_blob_read()]
33770 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f and [sqlite3_blo
33780 62 5f 77 72 69 74 65 28 29 5d 20 66 6f 72 0a 2a b_write()] for.*
33790 2a 20 61 20 65 78 70 69 72 65 64 20 42 4c 4f 42 * a expired BLOB
337a0 20 68 61 6e 64 6c 65 20 66 61 69 6c 20 77 69 74 handle fail wit
337b0 68 20 61 6e 20 72 65 74 75 72 6e 20 63 6f 64 65 h an return code
337c0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 of [SQLITE_ABOR
337d0 54 5d 2e 0a 2a 2a 20 43 68 61 6e 67 65 73 20 77 T]..** Changes w
337e0 72 69 74 74 65 6e 20 69 6e 74 6f 20 61 20 42 4c ritten into a BL
337f0 4f 42 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 OB prior to the
33800 42 4c 4f 42 20 65 78 70 69 72 69 6e 67 20 61 72 BLOB expiring ar
33810 65 20 6e 6f 74 0a 2a 2a 20 72 6f 6c 6c 62 61 63 e not.** rollbac
33820 6b 20 62 79 20 74 68 65 20 65 78 70 69 72 61 74 k by the expirat
33830 69 6f 6e 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e ion of the BLOB.
33840 20 20 53 75 63 68 20 63 68 61 6e 67 65 73 20 77 Such changes w
33850 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a ill eventually.*
33860 2a 20 63 6f 6d 6d 69 74 20 69 66 20 74 68 65 20 * commit if the
33870 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 transaction cont
33880 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 inues to complet
33890 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 73 65 20 74 ion..**.** Use t
338a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 he [sqlite3_blob
338b0 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 _bytes()] interf
338c0 61 63 65 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 ace to determine
338d0 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 the size of.**
338e0 74 68 65 20 6f 70 65 6e 65 64 20 62 6c 6f 62 2e the opened blob.
338f0 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 61 20 The size of a
33900 62 6c 6f 62 20 6d 61 79 20 6e 6f 74 20 62 65 20 blob may not be
33910 63 68 61 6e 67 65 64 20 62 79 20 74 68 69 73 0a changed by this.
33920 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 20 55 ** interface. U
33930 73 65 20 74 68 65 20 5b 55 50 44 41 54 45 5d 20 se the [UPDATE]
33940 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f 20 63 SQL command to c
33950 68 61 6e 67 65 20 74 68 65 20 73 69 7a 65 20 6f hange the size o
33960 66 20 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a 0a f a.** blob..**.
33970 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f ** The [sqlite3_
33980 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d bind_zeroblob()]
33990 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 and [sqlite3_re
339a0 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d sult_zeroblob()]
339b0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 interfaces.** a
339c0 6e 64 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 nd the built-in
339d0 5b 7a 65 72 6f 62 6c 6f 62 5d 20 53 51 4c 20 66 [zeroblob] SQL f
339e0 75 6e 63 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 unction can be u
339f0 73 65 64 2c 20 69 66 20 64 65 73 69 72 65 64 2c sed, if desired,
33a00 0a 2a 2a 20 74 6f 20 63 72 65 61 74 65 20 61 6e .** to create an
33a10 20 65 6d 70 74 79 2c 20 7a 65 72 6f 2d 66 69 6c empty, zero-fil
33a20 6c 65 64 20 62 6c 6f 62 20 69 6e 20 77 68 69 63 led blob in whic
33a30 68 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69 h to read or wri
33a40 74 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68 69 73 te using.** this
33a50 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a interface..**.*
33a60 2a 20 54 6f 20 61 76 6f 69 64 20 61 20 72 65 73 * To avoid a res
33a70 6f 75 72 63 65 20 6c 65 61 6b 2c 20 65 76 65 72 ource leak, ever
33a80 79 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e y open [BLOB han
33a90 64 6c 65 5d 20 73 68 6f 75 6c 64 20 65 76 65 6e dle] should even
33aa0 74 75 61 6c 6c 79 0a 2a 2a 20 62 65 20 72 65 6c tually.** be rel
33ab0 65 61 73 65 64 20 62 79 20 61 20 63 61 6c 6c 20 eased by a call
33ac0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 to [sqlite3_blob
33ad0 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a _close()]..**.**
33ae0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
33af0 2a 20 5b 48 31 37 38 31 33 5d 20 5b 48 31 37 38 * [H17813] [H178
33b00 31 34 5d 20 5b 48 31 37 38 31 36 5d 20 5b 48 31 14] [H17816] [H1
33b10 37 38 31 39 5d 20 5b 48 31 37 38 32 31 5d 20 5b 7819] [H17821] [
33b20 48 31 37 38 32 34 5d 0a 2a 2f 0a 53 51 4c 49 54 H17824].*/.SQLIT
33b30 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
33b40 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 3_blob_open(. s
33b50 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 qlite3*,. const
33b60 20 63 68 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f char *zDb,. co
33b70 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 nst char *zTable
33b80 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a ,. const char *
33b90 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 zColumn,. sqlit
33ba0 65 33 5f 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20 e3_int64 iRow,.
33bb0 20 69 6e 74 20 66 6c 61 67 73 2c 0a 20 20 73 71 int flags,. sq
33bc0 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 lite3_blob **ppB
33bd0 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 lob.);../*.** CA
33be0 50 49 33 52 45 46 3a 20 43 6c 6f 73 65 20 41 20 PI3REF: Close A
33bf0 42 4c 4f 42 20 48 61 6e 64 6c 65 20 7b 48 31 37 BLOB Handle {H17
33c00 38 33 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 830} <S30230>.**
33c10 0a 2a 2a 20 43 6c 6f 73 65 73 20 61 6e 20 6f 70 .** Closes an op
33c20 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d en [BLOB handle]
33c30 2e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 69 6e 67 20 ..**.** Closing
33c40 61 20 42 4c 4f 42 20 73 68 61 6c 6c 20 63 61 75 a BLOB shall cau
33c50 73 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 se the current t
33c60 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 63 6f ransaction to co
33c70 6d 6d 69 74 0a 2a 2a 20 69 66 20 74 68 65 72 65 mmit.** if there
33c80 20 61 72 65 20 6e 6f 20 6f 74 68 65 72 20 42 4c are no other BL
33c90 4f 42 73 2c 20 6e 6f 20 70 65 6e 64 69 6e 67 20 OBs, no pending
33ca0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
33cb0 6e 74 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 nts, and the.**
33cc0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
33cd0 69 6f 6e 20 69 73 20 69 6e 20 5b 61 75 74 6f 63 ion is in [autoc
33ce0 6f 6d 6d 69 74 20 6d 6f 64 65 5d 2e 0a 2a 2a 20 ommit mode]..**
33cf0 49 66 20 61 6e 79 20 77 72 69 74 65 73 20 77 65 If any writes we
33d00 72 65 20 6d 61 64 65 20 74 6f 20 74 68 65 20 42 re made to the B
33d10 4c 4f 42 2c 20 74 68 65 79 20 6d 69 67 68 74 20 LOB, they might
33d20 62 65 20 68 65 6c 64 20 69 6e 20 63 61 63 68 65 be held in cache
33d30 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20 63 6c .** until the cl
33d40 6f 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 66 ose operation if
33d50 20 74 68 65 79 20 77 69 6c 6c 20 66 69 74 2e 0a they will fit..
33d60 2a 2a 0a 2a 2a 20 43 6c 6f 73 69 6e 67 20 74 68 **.** Closing th
33d70 65 20 42 4c 4f 42 20 6f 66 74 65 6e 20 66 6f 72 e BLOB often for
33d80 63 65 73 20 74 68 65 20 63 68 61 6e 67 65 73 0a ces the changes.
33d90 2a 2a 20 6f 75 74 20 74 6f 20 64 69 73 6b 20 61 ** out to disk a
33da0 6e 64 20 73 6f 20 69 66 20 61 6e 79 20 49 2f 4f nd so if any I/O
33db0 20 65 72 72 6f 72 73 20 6f 63 63 75 72 2c 20 74 errors occur, t
33dc0 68 65 79 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 hey will likely
33dd0 6f 63 63 75 72 0a 2a 2a 20 61 74 20 74 68 65 20 occur.** at the
33de0 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 42 4c time when the BL
33df0 4f 42 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 41 OB is closed. A
33e00 6e 79 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f ny errors that o
33e10 63 63 75 72 20 64 75 72 69 6e 67 0a 2a 2a 20 63 ccur during.** c
33e20 6c 6f 73 69 6e 67 20 61 72 65 20 72 65 70 6f 72 losing are repor
33e30 74 65 64 20 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 ted as a non-zer
33e40 6f 20 72 65 74 75 72 6e 20 76 61 6c 75 65 2e 0a o return value..
33e50 2a 2a 0a 2a 2a 20 54 68 65 20 42 4c 4f 42 20 69 **.** The BLOB i
33e60 73 20 63 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 69 s closed uncondi
33e70 74 69 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 6e 20 tionally. Even
33e80 69 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 if this routine
33e90 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 72 returns.** an er
33ea0 72 6f 72 20 63 6f 64 65 2c 20 74 68 65 20 42 4c ror code, the BL
33eb0 4f 42 20 69 73 20 73 74 69 6c 6c 20 63 6c 6f 73 OB is still clos
33ec0 65 64 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e ed..**.** Callin
33ed0 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 g this routine w
33ee0 69 74 68 20 61 20 6e 75 6c 6c 20 70 6f 69 6e 74 ith a null point
33ef0 65 72 20 28 77 68 69 63 68 20 61 73 20 77 6f 75 er (which as wou
33f00 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 0a 2a ld be returned.*
33f10 2a 20 62 79 20 66 61 69 6c 65 64 20 63 61 6c 6c * by failed call
33f20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f to [sqlite3_blo
33f30 62 5f 6f 70 65 6e 28 29 5d 29 20 69 73 20 61 20 b_open()]) is a
33f40 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a harmless no-op..
33f50 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
33f60 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 33 33 5d 20 ts:.** [H17833]
33f70 5b 48 31 37 38 33 36 5d 20 5b 48 31 37 38 33 39 [H17836] [H17839
33f80 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
33f90 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 int sqlite3_blob
33fa0 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 5f 62 _close(sqlite3_b
33fb0 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 lob *);../*.** C
33fc0 41 50 49 33 52 45 46 3a 20 52 65 74 75 72 6e 20 API3REF: Return
33fd0 54 68 65 20 53 69 7a 65 20 4f 66 20 41 6e 20 4f The Size Of An O
33fe0 70 65 6e 20 42 4c 4f 42 20 7b 48 31 37 38 34 30 pen BLOB {H17840
33ff0 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a } <S30230>.**.**
34000 20 52 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a Returns the siz
34010 65 20 69 6e 20 62 79 74 65 73 20 6f 66 20 74 68 e in bytes of th
34020 65 20 42 4c 4f 42 20 61 63 63 65 73 73 69 62 6c e BLOB accessibl
34030 65 20 76 69 61 20 74 68 65 20 0a 2a 2a 20 73 75 e via the .** su
34040 63 63 65 73 73 66 75 6c 6c 79 20 6f 70 65 6e 65 ccessfully opene
34050 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 d [BLOB handle]
34060 69 6e 20 69 74 73 20 6f 6e 6c 79 20 61 72 67 75 in its only argu
34070 6d 65 6e 74 2e 20 20 54 68 65 0a 2a 2a 20 69 6e ment. The.** in
34080 63 72 65 6d 65 6e 74 61 6c 20 62 6c 6f 62 20 49 cremental blob I
34090 2f 4f 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 /O routines can
340a0 6f 6e 6c 79 20 72 65 61 64 20 6f 72 20 6f 76 65 only read or ove
340b0 72 77 72 69 74 69 6e 67 20 65 78 69 73 74 69 6e rwriting existin
340c0 67 0a 2a 2a 20 62 6c 6f 62 20 63 6f 6e 74 65 6e g.** blob conten
340d0 74 3b 20 74 68 65 79 20 63 61 6e 6e 6f 74 20 63 t; they cannot c
340e0 68 61 6e 67 65 20 74 68 65 20 73 69 7a 65 20 6f hange the size o
340f0 66 20 61 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 f a blob..**.**
34100 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c This routine onl
34110 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c y works on a [BL
34120 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 OB handle] which
34130 20 68 61 73 20 62 65 65 6e 20 63 72 65 61 74 65 has been create
34140 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20 d.** by a prior
34150 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 successful call
34160 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 to [sqlite3_blob
34170 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 _open()] and whi
34180 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 ch has not.** be
34190 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 en closed by [sq
341a0 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 lite3_blob_close
341b0 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e ()]. Passing an
341c0 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20 y other pointer
341d0 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f in.** to this ro
341e0 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e utine results in
341f0 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 undefined and p
34200 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 robably undesira
34210 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a ble behavior..**
34220 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
34230 3a 0a 2a 2a 20 5b 48 31 37 38 34 33 5d 0a 2a 2f :.** [H17843].*/
34240 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
34250 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 sqlite3_blob_byt
34260 65 73 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 es(sqlite3_blob
34270 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
34280 52 45 46 3a 20 52 65 61 64 20 44 61 74 61 20 46 REF: Read Data F
34290 72 6f 6d 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 rom A BLOB Incre
342a0 6d 65 6e 74 61 6c 6c 79 20 7b 48 31 37 38 35 30 mentally {H17850
342b0 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a } <S30230>.**.**
342c0 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 This function i
342d0 73 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 64 s used to read d
342e0 61 74 61 20 66 72 6f 6d 20 61 6e 20 6f 70 65 6e ata from an open
342f0 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 [BLOB handle] i
34300 6e 74 6f 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d nto a.** caller-
34310 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e supplied buffer.
34320 20 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 N bytes of data
34330 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f are copied into
34340 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20 66 72 6f buffer Z.** fro
34350 6d 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c m the open BLOB,
34360 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 starting at off
34370 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a set iOffset..**.
34380 2a 2a 20 49 66 20 6f 66 66 73 65 74 20 69 4f 66 ** If offset iOf
34390 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 fset is less tha
343a0 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 n N bytes from t
343b0 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c he end of the BL
343c0 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 OB,.** [SQLITE_E
343d0 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 RROR] is returne
343e0 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 d and no data is
343f0 20 72 65 61 64 2e 20 20 49 66 20 4e 20 6f 72 20 read. If N or
34400 69 4f 66 66 73 65 74 20 69 73 0a 2a 2a 20 6c 65 iOffset is.** le
34410 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 5b 53 ss than zero, [S
34420 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 QLITE_ERROR] is
34430 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 returned and no
34440 64 61 74 61 20 69 73 20 72 65 61 64 2e 0a 2a 2a data is read..**
34450 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 The size of the
34460 20 62 6c 6f 62 20 28 61 6e 64 20 68 65 6e 63 65 blob (and hence
34470 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c the maximum val
34480 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65 74 29 ue of N+iOffset)
34490 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 .** can be deter
344a0 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20 mined using the
344b0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 [sqlite3_blob_by
344c0 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 tes()] interface
344d0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 74 74 65 6d ..**.** An attem
344e0 70 74 20 74 6f 20 72 65 61 64 20 66 72 6f 6d 20 pt to read from
344f0 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c 4f 42 an expired [BLOB
34500 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77 handle] fails w
34510 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 ith an.** error
34520 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f code of [SQLITE_
34530 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 4f 6e ABORT]..**.** On
34540 20 73 75 63 63 65 73 73 2c 20 53 51 4c 49 54 45 success, SQLITE
34550 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e _OK is returned.
34560 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 61 .** Otherwise, a
34570 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f n [error code] o
34580 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 65 r an [extended e
34590 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 rror code] is re
345a0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 turned..**.** Th
345b0 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 is routine only
345c0 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 works on a [BLOB
345d0 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 handle] which h
345e0 61 73 20 62 65 65 6e 20 63 72 65 61 74 65 64 0a as been created.
345f0 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73 75 ** by a prior su
34600 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f ccessful call to
34610 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f [sqlite3_blob_o
34620 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 68 pen()] and which
34630 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e has not.** been
34640 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 closed by [sqli
34650 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 te3_blob_close()
34660 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79 20 ]. Passing any
34670 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69 6e other pointer in
34680 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 74 .** to this rout
34690 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20 75 ine results in u
346a0 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f ndefined and pro
346b0 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c bably undesirabl
346c0 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a e behavior..**.*
346d0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
346e0 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 ite3_blob_write(
346f0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 )]..**.** Requir
34700 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 ements:.** [H178
34710 35 33 5d 20 5b 48 31 37 38 35 36 5d 20 5b 48 31 53] [H17856] [H1
34720 37 38 35 39 5d 20 5b 48 31 37 38 36 32 5d 20 5b 7859] [H17862] [
34730 48 31 37 38 36 33 5d 20 5b 48 31 37 38 36 35 5d H17863] [H17865]
34740 20 5b 48 31 37 38 36 38 5d 0a 2a 2f 0a 53 51 4c [H17868].*/.SQL
34750 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
34760 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 73 71 te3_blob_read(sq
34770 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 76 6f lite3_blob *, vo
34780 69 64 20 2a 5a 2c 20 69 6e 74 20 4e 2c 20 69 6e id *Z, int N, in
34790 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a t iOffset);../*.
347a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 57 72 69 ** CAPI3REF: Wri
347b0 74 65 20 44 61 74 61 20 49 6e 74 6f 20 41 20 42 te Data Into A B
347c0 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c LOB Incrementall
347d0 79 20 7b 48 31 37 38 37 30 7d 20 3c 53 33 30 32 y {H17870} <S302
347e0 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 30>.**.** This f
347f0 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20 unction is used
34800 74 6f 20 77 72 69 74 65 20 64 61 74 61 20 69 6e to write data in
34810 74 6f 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 to an open [BLOB
34820 20 68 61 6e 64 6c 65 5d 20 66 72 6f 6d 20 61 0a handle] from a.
34830 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70 6c 69 ** caller-suppli
34840 65 64 20 62 75 66 66 65 72 2e 20 4e 20 62 79 74 ed buffer. N byt
34850 65 73 20 6f 66 20 64 61 74 61 20 61 72 65 20 63 es of data are c
34860 6f 70 69 65 64 20 66 72 6f 6d 20 74 68 65 20 62 opied from the b
34870 75 66 66 65 72 20 5a 0a 2a 2a 20 69 6e 74 6f 20 uffer Z.** into
34880 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 the open BLOB, s
34890 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65 tarting at offse
348a0 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a t iOffset..**.**
348b0 20 49 66 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 If the [BLOB ha
348c0 6e 64 6c 65 5d 20 70 61 73 73 65 64 20 61 73 20 ndle] passed as
348d0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
348e0 6e 74 20 77 61 73 20 6e 6f 74 20 6f 70 65 6e 65 nt was not opene
348f0 64 20 66 6f 72 0a 2a 2a 20 77 72 69 74 69 6e 67 d for.** writing
34900 20 28 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 (the flags para
34910 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 meter to [sqlite
34920 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 77 3_blob_open()] w
34930 61 73 20 7a 65 72 6f 29 2c 0a 2a 2a 20 74 68 69 as zero),.** thi
34940 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 s function retur
34950 6e 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 4f ns [SQLITE_READO
34960 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 NLY]..**.** This
34970 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6f 6e function may on
34980 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 63 6f ly modify the co
34990 6e 74 65 6e 74 73 20 6f 66 20 74 68 65 20 42 4c ntents of the BL
349a0 4f 42 3b 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 OB; it is.** not
349b0 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 63 possible to inc
349c0 72 65 61 73 65 20 74 68 65 20 73 69 7a 65 20 6f rease the size o
349d0 66 20 61 20 42 4c 4f 42 20 75 73 69 6e 67 20 74 f a BLOB using t
349e0 68 69 73 20 41 50 49 2e 0a 2a 2a 20 49 66 20 6f his API..** If o
349f0 66 66 73 65 74 20 69 4f 66 66 73 65 74 20 69 73 ffset iOffset is
34a00 20 6c 65 73 73 20 74 68 61 6e 20 4e 20 62 79 74 less than N byt
34a10 65 73 20 66 72 6f 6d 20 74 68 65 20 65 6e 64 20 es from the end
34a20 6f 66 20 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 of the BLOB,.**
34a30 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 [SQLITE_ERROR] i
34a40 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e s returned and n
34a50 6f 20 64 61 74 61 20 69 73 20 77 72 69 74 74 65 o data is writte
34a60 6e 2e 20 20 49 66 20 4e 20 69 73 0a 2a 2a 20 6c n. If N is.** l
34a70 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 20 5b 53 ess than zero [S
34a80 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 QLITE_ERROR] is
34a90 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 returned and no
34aa0 64 61 74 61 20 69 73 20 77 72 69 74 74 65 6e 2e data is written.
34ab0 0a 2a 2a 20 54 68 65 20 73 69 7a 65 20 6f 66 20 .** The size of
34ac0 74 68 65 20 42 4c 4f 42 20 28 61 6e 64 20 68 65 the BLOB (and he
34ad0 6e 63 65 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 nce the maximum
34ae0 76 61 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 value of N+iOffs
34af0 65 74 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 et).** can be de
34b00 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 termined using t
34b10 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 he [sqlite3_blob
34b20 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 _bytes()] interf
34b30 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 74 ace..**.** An at
34b40 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 74 tempt to write t
34b50 6f 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c o an expired [BL
34b60 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 OB handle] fails
34b70 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f with an.** erro
34b80 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 r code of [SQLIT
34b90 45 5f 41 42 4f 52 54 5d 2e 20 20 57 72 69 74 65 E_ABORT]. Write
34ba0 73 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 74 68 s to the BLOB th
34bb0 61 74 20 6f 63 63 75 72 72 65 64 0a 2a 2a 20 62 at occurred.** b
34bc0 65 66 6f 72 65 20 74 68 65 20 5b 42 4c 4f 42 20 efore the [BLOB
34bd0 68 61 6e 64 6c 65 5d 20 65 78 70 69 72 65 64 20 handle] expired
34be0 61 72 65 20 6e 6f 74 20 72 6f 6c 6c 65 64 20 62 are not rolled b
34bf0 61 63 6b 20 62 79 20 74 68 65 0a 2a 2a 20 65 78 ack by the.** ex
34c00 70 69 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 piration of the
34c10 68 61 6e 64 6c 65 2c 20 74 68 6f 75 67 68 20 6f handle, though o
34c20 66 20 63 6f 75 72 73 65 20 74 68 6f 73 65 20 63 f course those c
34c30 68 61 6e 67 65 73 20 6d 69 67 68 74 0a 2a 2a 20 hanges might.**
34c40 68 61 76 65 20 62 65 65 6e 20 6f 76 65 72 77 72 have been overwr
34c50 69 74 74 65 6e 20 62 79 20 74 68 65 20 73 74 61 itten by the sta
34c60 74 65 6d 65 6e 74 20 74 68 61 74 20 65 78 70 69 tement that expi
34c70 72 65 64 20 74 68 65 20 42 4c 4f 42 20 68 61 6e red the BLOB han
34c80 64 6c 65 0a 2a 2a 20 6f 72 20 62 79 20 6f 74 68 dle.** or by oth
34c90 65 72 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 73 er independent s
34ca0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a tatements..**.**
34cb0 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 53 51 4c On success, SQL
34cc0 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e ITE_OK is return
34cd0 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 ed..** Otherwise
34ce0 2c 20 61 6e 20 20 5b 65 72 72 6f 72 20 63 6f 64 , an [error cod
34cf0 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 e] or an [extend
34d00 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 ed error code] i
34d10 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a s returned..**.*
34d20 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f * This routine o
34d30 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b nly works on a [
34d40 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69 BLOB handle] whi
34d50 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 65 61 ch has been crea
34d60 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f ted.** by a prio
34d70 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c r successful cal
34d80 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c l to [sqlite3_bl
34d90 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77 ob_open()] and w
34da0 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 hich has not.**
34db0 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b been closed by [
34dc0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f sqlite3_blob_clo
34dd0 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20 se()]. Passing
34de0 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65 any other pointe
34df0 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20 r in.** to this
34e00 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20 routine results
34e10 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 in undefined and
34e20 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 probably undesi
34e30 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a rable behavior..
34e40 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
34e50 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 [sqlite3_blob_re
34e60 61 64 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 ad()]..**.** Req
34e70 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
34e80 31 37 38 37 33 5d 20 5b 48 31 37 38 37 34 5d 20 17873] [H17874]
34e90 5b 48 31 37 38 37 35 5d 20 5b 48 31 37 38 37 36 [H17875] [H17876
34ea0 5d 20 5b 48 31 37 38 37 37 5d 20 5b 48 31 37 38 ] [H17877] [H178
34eb0 37 39 5d 20 5b 48 31 37 38 38 32 5d 20 5b 48 31 79] [H17882] [H1
34ec0 37 38 38 35 5d 0a 2a 2a 20 5b 48 31 37 38 38 38 7885].** [H17888
34ed0 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
34ee0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 int sqlite3_blob
34ef0 5f 77 72 69 74 65 28 73 71 6c 69 74 65 33 5f 62 _write(sqlite3_b
34f00 6c 6f 62 20 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 lob *, const voi
34f10 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 d *z, int n, int
34f20 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a iOffset);../*.*
34f30 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 * CAPI3REF: Virt
34f40 75 61 6c 20 46 69 6c 65 20 53 79 73 74 65 6d 20 ual File System
34f50 4f 62 6a 65 63 74 73 20 7b 48 31 31 32 30 30 7d Objects {H11200}
34f60 20 3c 53 32 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S20100>.**.**
34f70 41 20 76 69 72 74 75 61 6c 20 66 69 6c 65 73 79 A virtual filesy
34f80 73 74 65 6d 20 28 56 46 53 29 20 69 73 20 61 6e stem (VFS) is an
34f90 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f [sqlite3_vfs] o
34fa0 62 6a 65 63 74 0a 2a 2a 20 74 68 61 74 20 53 51 bject.** that SQ
34fb0 4c 69 74 65 20 75 73 65 73 20 74 6f 20 69 6e 74 Lite uses to int
34fc0 65 72 61 63 74 0a 2a 2a 20 77 69 74 68 20 74 68 eract.** with th
34fd0 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 e underlying ope
34fe0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 rating system.
34ff0 4d 6f 73 74 20 53 51 4c 69 74 65 20 62 75 69 6c Most SQLite buil
35000 64 73 20 63 6f 6d 65 20 77 69 74 68 20 61 0a 2a ds come with a.*
35010 2a 20 73 69 6e 67 6c 65 20 64 65 66 61 75 6c 74 * single default
35020 20 56 46 53 20 74 68 61 74 20 69 73 20 61 70 70 VFS that is app
35030 72 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68 65 ropriate for the
35040 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a host computer..
35050 2a 2a 20 4e 65 77 20 56 46 53 65 73 20 63 61 6e ** New VFSes can
35060 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 61 be registered a
35070 6e 64 20 65 78 69 73 74 69 6e 67 20 56 46 53 65 nd existing VFSe
35080 73 20 63 61 6e 20 62 65 20 75 6e 72 65 67 69 73 s can be unregis
35090 74 65 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f tered..** The fo
350a0 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 llowing interfac
350b0 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 2e es are provided.
350c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
350d0 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 20 69 6e e3_vfs_find() in
350e0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
350f0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 56 a pointer to a V
35100 46 53 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d FS given its nam
35110 65 2e 0a 2a 2a 20 4e 61 6d 65 73 20 61 72 65 20 e..** Names are
35120 63 61 73 65 20 73 65 6e 73 69 74 69 76 65 2e 0a case sensitive..
35130 2a 2a 20 4e 61 6d 65 73 20 61 72 65 20 7a 65 72 ** Names are zer
35140 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 o-terminated UTF
35150 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 49 -8 strings..** I
35160 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 61 f there is no ma
35170 74 63 68 2c 20 61 20 4e 55 4c 4c 20 70 6f 69 6e tch, a NULL poin
35180 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e ter is returned.
35190 0a 2a 2a 20 49 66 20 7a 56 66 73 4e 61 6d 65 20 .** If zVfsName
351a0 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 is NULL then the
351b0 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 default VFS is
351c0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
351d0 4e 65 77 20 56 46 53 65 73 20 61 72 65 20 72 65 New VFSes are re
351e0 67 69 73 74 65 72 65 64 20 77 69 74 68 20 73 71 gistered with sq
351f0 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 lite3_vfs_regist
35200 65 72 28 29 2e 0a 2a 2a 20 45 61 63 68 20 6e 65 er()..** Each ne
35210 77 20 56 46 53 20 62 65 63 6f 6d 65 73 20 74 68 w VFS becomes th
35220 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 66 e default VFS if
35230 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c the makeDflt fl
35240 61 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20 54 68 ag is set..** Th
35250 65 20 73 61 6d 65 20 56 46 53 20 63 61 6e 20 62 e same VFS can b
35260 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c e registered mul
35270 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68 tiple times with
35280 6f 75 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20 54 out injury..** T
35290 6f 20 6d 61 6b 65 20 61 6e 20 65 78 69 73 74 69 o make an existi
352a0 6e 67 20 56 46 53 20 69 6e 74 6f 20 74 68 65 20 ng VFS into the
352b0 64 65 66 61 75 6c 74 20 56 46 53 2c 20 72 65 67 default VFS, reg
352c0 69 73 74 65 72 20 69 74 20 61 67 61 69 6e 0a 2a ister it again.*
352d0 2a 20 77 69 74 68 20 74 68 65 20 6d 61 6b 65 44 * with the makeD
352e0 66 6c 74 20 66 6c 61 67 20 73 65 74 2e 20 20 49 flt flag set. I
352f0 66 20 74 77 6f 20 64 69 66 66 65 72 65 6e 74 20 f two different
35300 56 46 53 65 73 20 77 69 74 68 20 74 68 65 0a 2a VFSes with the.*
35310 2a 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 * same name are
35320 72 65 67 69 73 74 65 72 65 64 2c 20 74 68 65 20 registered, the
35330 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 behavior is unde
35340 66 69 6e 65 64 2e 20 20 49 66 20 61 0a 2a 2a 20 fined. If a.**
35350 56 46 53 20 69 73 20 72 65 67 69 73 74 65 72 65 VFS is registere
35360 64 20 77 69 74 68 20 61 20 6e 61 6d 65 20 74 68 d with a name th
35370 61 74 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e at is NULL or an
35380 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 0a 2a empty string,.*
35390 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 * then the behav
353a0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ior is undefined
353b0 2e 0a 2a 2a 0a 2a 2a 20 55 6e 72 65 67 69 73 74 ..**.** Unregist
353c0 65 72 20 61 20 56 46 53 20 77 69 74 68 20 74 68 er a VFS with th
353d0 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e e sqlite3_vfs_un
353e0 72 65 67 69 73 74 65 72 28 29 20 69 6e 74 65 72 register() inter
353f0 66 61 63 65 2e 0a 2a 2a 20 49 66 20 74 68 65 20 face..** If the
35400 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 75 default VFS is u
35410 6e 72 65 67 69 73 74 65 72 65 64 2c 20 61 6e 6f nregistered, ano
35420 74 68 65 72 20 56 46 53 20 69 73 20 63 68 6f 73 ther VFS is chos
35430 65 6e 20 61 73 0a 2a 2a 20 74 68 65 20 64 65 66 en as.** the def
35440 61 75 6c 74 2e 20 20 54 68 65 20 63 68 6f 69 63 ault. The choic
35450 65 20 66 6f 72 20 74 68 65 20 6e 65 77 20 56 46 e for the new VF
35460 53 20 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a S is arbitrary..
35470 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
35480 74 73 3a 0a 2a 2a 20 5b 48 31 31 32 30 33 5d 20 ts:.** [H11203]
35490 5b 48 31 31 32 30 36 5d 20 5b 48 31 31 32 30 39 [H11206] [H11209
354a0 5d 20 5b 48 31 31 32 31 32 5d 20 5b 48 31 31 32 ] [H11212] [H112
354b0 31 35 5d 20 5b 48 31 31 32 31 38 5d 0a 2a 2f 0a 15] [H11218].*/.
354c0 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 SQLITE_API sqlit
354d0 65 33 5f 76 66 73 20 2a 73 71 6c 69 74 65 33 5f e3_vfs *sqlite3_
354e0 76 66 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20 63 vfs_find(const c
354f0 68 61 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a har *zVfsName);.
35500 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
35510 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 qlite3_vfs_regis
35520 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ter(sqlite3_vfs*
35530 2c 20 69 6e 74 20 6d 61 6b 65 44 66 6c 74 29 3b , int makeDflt);
35540 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
35550 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 sqlite3_vfs_unre
35560 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76 gister(sqlite3_v
35570 66 73 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 fs*);../*.** CAP
35580 49 33 52 45 46 3a 20 4d 75 74 65 78 65 73 20 7b I3REF: Mutexes {
35590 48 31 37 30 30 30 7d 20 3c 53 32 30 30 30 30 3e H17000} <S20000>
355a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 .**.** The SQLit
355b0 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 e core uses thes
355c0 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 74 e routines for t
355d0 68 72 65 61 64 0a 2a 2a 20 73 79 6e 63 68 72 6f hread.** synchro
355e0 6e 69 7a 61 74 69 6f 6e 2e 20 54 68 6f 75 67 68 nization. Though
355f0 20 74 68 65 79 20 61 72 65 20 69 6e 74 65 6e 64 they are intend
35600 65 64 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a ed for internal.
35610 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 ** use by SQLite
35620 2c 20 63 6f 64 65 20 74 68 61 74 20 6c 69 6e 6b , code that link
35630 73 20 61 67 61 69 6e 73 74 20 53 51 4c 69 74 65 s against SQLite
35640 20 69 73 0a 2a 2a 20 70 65 72 6d 69 74 74 65 64 is.** permitted
35650 20 74 6f 20 75 73 65 20 61 6e 79 20 6f 66 20 74 to use any of t
35660 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a hese routines..*
35670 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 *.** The SQLite
35680 73 6f 75 72 63 65 20 63 6f 64 65 20 63 6f 6e 74 source code cont
35690 61 69 6e 73 20 6d 75 6c 74 69 70 6c 65 20 69 6d ains multiple im
356a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a plementations.**
356b0 20 6f 66 20 74 68 65 73 65 20 6d 75 74 65 78 20 of these mutex
356c0 72 6f 75 74 69 6e 65 73 2e 20 20 41 6e 20 61 70 routines. An ap
356d0 70 72 6f 70 72 69 61 74 65 20 69 6d 70 6c 65 6d propriate implem
356e0 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 73 entation.** is s
356f0 65 6c 65 63 74 65 64 20 61 75 74 6f 6d 61 74 69 elected automati
35700 63 61 6c 6c 79 20 61 74 20 63 6f 6d 70 69 6c 65 cally at compile
35710 2d 74 69 6d 65 2e 20 20 54 68 65 20 66 6f 6c 6c -time. The foll
35720 6f 77 69 6e 67 0a 2a 2a 20 69 6d 70 6c 65 6d 65 owing.** impleme
35730 6e 74 61 74 69 6f 6e 73 20 61 72 65 20 61 76 61 ntations are ava
35740 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 53 51 ilable in the SQ
35750 4c 69 74 65 20 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a Lite core:.**.**
35760 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20 <ul>.** <li>
35770 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 SQLITE_MUTEX_OS2
35780 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 .** <li> SQLIT
35790 45 5f 4d 55 54 45 58 5f 50 54 48 52 45 41 44 0a E_MUTEX_PTHREAD.
357a0 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 ** <li> SQLITE
357b0 5f 4d 55 54 45 58 5f 57 33 32 0a 2a 2a 20 3c 6c _MUTEX_W32.** <l
357c0 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 i> SQLITE_MUTE
357d0 58 5f 4e 4f 4f 50 0a 2a 2a 20 3c 2f 75 6c 3e 0a X_NOOP.** </ul>.
357e0 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 **.** The SQLITE
357f0 5f 4d 55 54 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c _MUTEX_NOOP impl
35800 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61 20 ementation is a
35810 73 65 74 20 6f 66 20 72 6f 75 74 69 6e 65 73 0a set of routines.
35820 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 20 ** that does no
35830 72 65 61 6c 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 real locking and
35840 20 69 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 is appropriate
35850 66 6f 72 20 75 73 65 20 69 6e 0a 2a 2a 20 61 20 for use in.** a
35860 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 20 single-threaded
35870 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 application. Th
35880 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f e SQLITE_MUTEX_O
35890 53 32 2c 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 S2,.** SQLITE_MU
358a0 54 45 58 5f 50 54 48 52 45 41 44 2c 20 61 6e 64 TEX_PTHREAD, and
358b0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 SQLITE_MUTEX_W3
358c0 32 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2 implementation
358d0 73 0a 2a 2a 20 61 72 65 20 61 70 70 72 6f 70 72 s.** are appropr
358e0 69 61 74 65 20 66 6f 72 20 75 73 65 20 6f 6e 20 iate for use on
358f0 4f 53 2f 32 2c 20 55 6e 69 78 2c 20 61 6e 64 20 OS/2, Unix, and
35900 57 69 6e 64 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 49 Windows..**.** I
35910 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 f SQLite is comp
35920 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 iled with the SQ
35930 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 LITE_MUTEX_APPDE
35940 46 20 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a F preprocessor.*
35950 2a 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20 * macro defined
35960 28 77 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f (with "-DSQLITE_
35970 4d 55 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29 MUTEX_APPDEF=1")
35980 2c 20 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a , then no mutex.
35990 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
359a0 6e 20 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69 n is included wi
359b0 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20 th the library.
359c0 49 6e 20 74 68 69 73 20 63 61 73 65 20 74 68 65 In this case the
359d0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 .** application
359e0 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 63 75 must supply a cu
359f0 73 74 6f 6d 20 6d 75 74 65 78 20 69 6d 70 6c 65 stom mutex imple
35a00 6d 65 6e 74 61 74 69 6f 6e 20 75 73 69 6e 67 20 mentation using
35a10 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 the.** [SQLITE_C
35a20 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 ONFIG_MUTEX] opt
35a30 69 6f 6e 20 6f 66 20 74 68 65 20 73 71 6c 69 74 ion of the sqlit
35a40 65 33 5f 63 6f 6e 66 69 67 28 29 20 66 75 6e 63 e3_config() func
35a50 74 69 6f 6e 0a 2a 2a 20 62 65 66 6f 72 65 20 63 tion.** before c
35a60 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 69 alling sqlite3_i
35a70 6e 69 74 69 61 6c 69 7a 65 28 29 20 6f 72 20 61 nitialize() or a
35a80 6e 79 20 6f 74 68 65 72 20 70 75 62 6c 69 63 20 ny other public
35a90 73 71 6c 69 74 65 33 5f 0a 2a 2a 20 66 75 6e 63 sqlite3_.** func
35aa0 74 69 6f 6e 20 74 68 61 74 20 63 61 6c 6c 73 20 tion that calls
35ab0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
35ac0 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 ze()..**.** {H17
35ad0 30 31 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 011} The sqlite3
35ae0 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 72 _mutex_alloc() r
35af0 6f 75 74 69 6e 65 20 61 6c 6c 6f 63 61 74 65 73 outine allocates
35b00 20 61 20 6e 65 77 0a 2a 2a 20 6d 75 74 65 78 20 a new.** mutex
35b10 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f and returns a po
35b20 69 6e 74 65 72 20 74 6f 20 69 74 2e 20 7b 48 31 inter to it. {H1
35b30 37 30 31 32 7d 20 49 66 20 69 74 20 72 65 74 75 7012} If it retu
35b40 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74 rns NULL.** that
35b50 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 6d 75 means that a mu
35b60 74 65 78 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 tex could not be
35b70 20 61 6c 6c 6f 63 61 74 65 64 2e 20 7b 48 31 37 allocated. {H17
35b80 30 31 33 7d 20 53 51 4c 69 74 65 0a 2a 2a 20 77 013} SQLite.** w
35b90 69 6c 6c 20 75 6e 77 69 6e 64 20 69 74 73 20 73 ill unwind its s
35ba0 74 61 63 6b 20 61 6e 64 20 72 65 74 75 72 6e 20 tack and return
35bb0 61 6e 20 65 72 72 6f 72 2e 20 7b 48 31 37 30 31 an error. {H1701
35bc0 34 7d 20 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 4} The argument.
35bd0 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 ** to sqlite3_mu
35be0 74 65 78 5f 61 6c 6c 6f 63 28 29 20 69 73 20 6f tex_alloc() is o
35bf0 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 ne of these inte
35c00 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a ger constants:.*
35c10 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
35c20 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f > SQLITE_MUTEX_
35c30 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 FAST.** <li> SQ
35c40 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 LITE_MUTEX_RECUR
35c50 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 SIVE.** <li> SQ
35c60 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 LITE_MUTEX_STATI
35c70 43 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c 6c 69 3e C_MASTER.** <li>
35c80 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 SQLITE_MUTEX_S
35c90 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69 TATIC_MEM.** <li
35ca0 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f > SQLITE_MUTEX_
35cb0 53 54 41 54 49 43 5f 4d 45 4d 32 0a 2a 2a 20 3c STATIC_MEM2.** <
35cc0 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 li> SQLITE_MUTE
35cd0 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 0a 2a 2a X_STATIC_PRNG.**
35ce0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 <li> SQLITE_MU
35cf0 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 0a 2a TEX_STATIC_LRU.*
35d00 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d * <li> SQLITE_M
35d10 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 32 UTEX_STATIC_LRU2
35d20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
35d30 7b 48 31 37 30 31 35 7d 20 54 68 65 20 66 69 72 {H17015} The fir
35d40 73 74 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 st two constants
35d50 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 6d cause sqlite3_m
35d60 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20 utex_alloc() to
35d70 63 72 65 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20 create.** a new
35d80 6d 75 74 65 78 2e 20 20 54 68 65 20 6e 65 77 20 mutex. The new
35d90 6d 75 74 65 78 20 69 73 20 72 65 63 75 72 73 69 mutex is recursi
35da0 76 65 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d ve when SQLITE_M
35db0 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a UTEX_RECURSIVE.*
35dc0 2a 20 69 73 20 75 73 65 64 20 62 75 74 20 6e 6f * is used but no
35dd0 74 20 6e 65 63 65 73 73 61 72 69 6c 79 20 73 6f t necessarily so
35de0 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 when SQLITE_MUT
35df0 45 58 5f 46 41 53 54 20 69 73 20 75 73 65 64 2e EX_FAST is used.
35e00 20 7b 45 4e 44 7d 0a 2a 2a 20 54 68 65 20 6d 75 {END}.** The mu
35e10 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 tex implementati
35e20 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 on does not need
35e30 20 74 6f 20 6d 61 6b 65 20 61 20 64 69 73 74 69 to make a disti
35e40 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 nction.** betwee
35e50 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 n SQLITE_MUTEX_R
35e60 45 43 55 52 53 49 56 45 20 61 6e 64 20 53 51 4c ECURSIVE and SQL
35e70 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 69 ITE_MUTEX_FAST i
35e80 66 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 f it does.** not
35e90 20 77 61 6e 74 20 74 6f 2e 20 20 7b 48 31 37 30 want to. {H170
35ea0 31 36 7d 20 42 75 74 20 53 51 4c 69 74 65 20 77 16} But SQLite w
35eb0 69 6c 6c 20 6f 6e 6c 79 20 72 65 71 75 65 73 74 ill only request
35ec0 20 61 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 a recursive mut
35ed0 65 78 20 69 6e 0a 2a 2a 20 63 61 73 65 73 20 77 ex in.** cases w
35ee0 68 65 72 65 20 69 74 20 72 65 61 6c 6c 79 20 6e here it really n
35ef0 65 65 64 73 20 6f 6e 65 2e 20 20 7b 45 4e 44 7d eeds one. {END}
35f00 20 49 66 20 61 20 66 61 73 74 65 72 20 6e 6f 6e If a faster non
35f10 2d 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 -recursive mutex
35f20 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
35f30 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 on is available
35f40 6f 6e 20 74 68 65 20 68 6f 73 74 20 70 6c 61 74 on the host plat
35f50 66 6f 72 6d 2c 20 74 68 65 20 6d 75 74 65 78 20 form, the mutex
35f60 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20 6d 69 67 subsystem.** mig
35f70 68 74 20 72 65 74 75 72 6e 20 73 75 63 68 20 61 ht return such a
35f80 20 6d 75 74 65 78 20 69 6e 20 72 65 73 70 6f 6e mutex in respon
35f90 73 65 20 74 6f 20 53 51 4c 49 54 45 5f 4d 55 54 se to SQLITE_MUT
35fa0 45 58 5f 46 41 53 54 2e 0a 2a 2a 0a 2a 2a 20 7b EX_FAST..**.** {
35fb0 48 31 37 30 31 37 7d 20 54 68 65 20 6f 74 68 65 H17017} The othe
35fc0 72 20 61 6c 6c 6f 77 65 64 20 70 61 72 61 6d 65 r allowed parame
35fd0 74 65 72 73 20 74 6f 20 73 71 6c 69 74 65 33 5f ters to sqlite3_
35fe0 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 65 61 mutex_alloc() ea
35ff0 63 68 20 72 65 74 75 72 6e 0a 2a 2a 20 61 20 70 ch return.** a p
36000 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 61 74 ointer to a stat
36010 69 63 20 70 72 65 65 78 69 73 74 69 6e 67 20 6d ic preexisting m
36020 75 74 65 78 2e 20 7b 45 4e 44 7d 20 20 53 69 78 utex. {END} Six
36030 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 static mutexes
36040 61 72 65 0a 2a 2a 20 75 73 65 64 20 62 79 20 74 are.** used by t
36050 68 65 20 63 75 72 72 65 6e 74 20 76 65 72 73 69 he current versi
36060 6f 6e 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 46 on of SQLite. F
36070 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f uture versions o
36080 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 61 79 20 f SQLite.** may
36090 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 add additional s
360a0 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e 20 20 tatic mutexes.
360b0 53 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 Static mutexes a
360c0 72 65 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a re for internal.
360d0 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 ** use by SQLite
360e0 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 only. Applicat
360f0 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 53 51 ions that use SQ
36100 4c 69 74 65 20 6d 75 74 65 78 65 73 20 73 68 6f Lite mutexes sho
36110 75 6c 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79 20 uld.** use only
36120 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 the dynamic mute
36130 78 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 xes returned by
36140 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 SQLITE_MUTEX_FAS
36150 54 20 6f 72 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d T or.** SQLITE_M
36160 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 2e 0a UTEX_RECURSIVE..
36170 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 38 7d 20 4e **.** {H17018} N
36180 6f 74 65 20 74 68 61 74 20 69 66 20 6f 6e 65 20 ote that if one
36190 6f 66 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d of the dynamic m
361a0 75 74 65 78 20 70 61 72 61 6d 65 74 65 72 73 20 utex parameters
361b0 28 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 (SQLITE_MUTEX_FA
361c0 53 54 0a 2a 2a 20 6f 72 20 53 51 4c 49 54 45 5f ST.** or SQLITE_
361d0 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 29 MUTEX_RECURSIVE)
361e0 20 69 73 20 75 73 65 64 20 74 68 65 6e 20 73 71 is used then sq
361f0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f lite3_mutex_allo
36200 63 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 c().** returns a
36210 20 64 69 66 66 65 72 65 6e 74 20 6d 75 74 65 78 different mutex
36220 20 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 2e 20 on every call.
36230 20 7b 48 31 37 30 33 34 7d 20 42 75 74 20 66 6f {H17034} But fo
36240 72 20 74 68 65 20 73 74 61 74 69 63 0a 2a 2a 20 r the static.**
36250 6d 75 74 65 78 20 74 79 70 65 73 2c 20 74 68 65 mutex types, the
36260 20 73 61 6d 65 20 6d 75 74 65 78 20 69 73 20 72 same mutex is r
36270 65 74 75 72 6e 65 64 20 6f 6e 20 65 76 65 72 79 eturned on every
36280 20 63 61 6c 6c 20 74 68 61 74 20 68 61 73 0a 2a call that has.*
36290 2a 20 74 68 65 20 73 61 6d 65 20 74 79 70 65 20 * the same type
362a0 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 number..**.** {H
362b0 31 37 30 31 39 7d 20 54 68 65 20 73 71 6c 69 74 17019} The sqlit
362c0 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 20 e3_mutex_free()
362d0 72 6f 75 74 69 6e 65 20 64 65 61 6c 6c 6f 63 61 routine dealloca
362e0 74 65 73 20 61 20 70 72 65 76 69 6f 75 73 6c 79 tes a previously
362f0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 64 79 .** allocated dy
36300 6e 61 6d 69 63 20 6d 75 74 65 78 2e 20 7b 48 31 namic mutex. {H1
36310 37 30 32 30 7d 20 53 51 4c 69 74 65 20 69 73 20 7020} SQLite is
36320 63 61 72 65 66 75 6c 20 74 6f 20 64 65 61 6c 6c careful to deall
36330 6f 63 61 74 65 20 65 76 65 72 79 0a 2a 2a 20 64 ocate every.** d
36340 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 74 68 61 ynamic mutex tha
36350 74 20 69 74 20 61 6c 6c 6f 63 61 74 65 73 2e 20 t it allocates.
36360 7b 41 31 37 30 32 31 7d 20 54 68 65 20 64 79 6e {A17021} The dyn
36370 61 6d 69 63 20 6d 75 74 65 78 65 73 20 6d 75 73 amic mutexes mus
36380 74 20 6e 6f 74 20 62 65 20 69 6e 0a 2a 2a 20 75 t not be in.** u
36390 73 65 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 se when they are
363a0 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 20 7b 41 deallocated. {A
363b0 31 37 30 32 32 7d 20 41 74 74 65 6d 70 74 69 6e 17022} Attemptin
363c0 67 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 g to deallocate
363d0 61 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 a static.** mute
363e0 78 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 x results in und
363f0 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e efined behavior.
36400 20 7b 48 31 37 30 32 33 7d 20 53 51 4c 69 74 65 {H17023} SQLite
36410 20 6e 65 76 65 72 20 64 65 61 6c 6c 6f 63 61 74 never deallocat
36420 65 73 0a 2a 2a 20 61 20 73 74 61 74 69 63 20 6d es.** a static m
36430 75 74 65 78 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a utex. {END}.**.*
36440 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 * The sqlite3_mu
36450 74 65 78 5f 65 6e 74 65 72 28 29 20 61 6e 64 20 tex_enter() and
36460 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 sqlite3_mutex_tr
36470 79 28 29 20 72 6f 75 74 69 6e 65 73 20 61 74 74 y() routines att
36480 65 6d 70 74 0a 2a 2a 20 74 6f 20 65 6e 74 65 72 empt.** to enter
36490 20 61 20 6d 75 74 65 78 2e 20 7b 48 31 37 30 32 a mutex. {H1702
364a0 34 7d 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 4} If another th
364b0 72 65 61 64 20 69 73 20 61 6c 72 65 61 64 79 20 read is already
364c0 77 69 74 68 69 6e 20 74 68 65 20 6d 75 74 65 78 within the mutex
364d0 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 ,.** sqlite3_mut
364e0 65 78 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c 20 ex_enter() will
364f0 62 6c 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74 65 block and sqlite
36500 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 77 69 3_mutex_try() wi
36510 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c ll return.** SQL
36520 49 54 45 5f 42 55 53 59 2e 20 7b 48 31 37 30 32 ITE_BUSY. {H1702
36530 35 7d 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 5} The sqlite3_
36540 6d 75 74 65 78 5f 74 72 79 28 29 20 69 6e 74 65 mutex_try() inte
36550 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 5b 53 rface returns [S
36560 51 4c 49 54 45 5f 4f 4b 5d 0a 2a 2a 20 75 70 6f QLITE_OK].** upo
36570 6e 20 73 75 63 63 65 73 73 66 75 6c 20 65 6e 74 n successful ent
36580 72 79 2e 20 20 7b 48 31 37 30 32 36 7d 20 4d 75 ry. {H17026} Mu
36590 74 65 78 65 73 20 63 72 65 61 74 65 64 20 75 73 texes created us
365a0 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 ing.** SQLITE_MU
365b0 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 63 61 TEX_RECURSIVE ca
365c0 6e 20 62 65 20 65 6e 74 65 72 65 64 20 6d 75 6c n be entered mul
365d0 74 69 70 6c 65 20 74 69 6d 65 73 20 62 79 20 74 tiple times by t
365e0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e 0a he same thread..
365f0 2a 2a 20 7b 48 31 37 30 32 37 7d 20 49 6e 20 73 ** {H17027} In s
36600 75 63 68 20 63 61 73 65 73 20 74 68 65 2c 0a 2a uch cases the,.*
36610 2a 20 6d 75 74 65 78 20 6d 75 73 74 20 62 65 20 * mutex must be
36620 65 78 69 74 65 64 20 61 6e 20 65 71 75 61 6c 20 exited an equal
36630 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 number of times
36640 62 65 66 6f 72 65 20 61 6e 6f 74 68 65 72 20 74 before another t
36650 68 72 65 61 64 0a 2a 2a 20 63 61 6e 20 65 6e 74 hread.** can ent
36660 65 72 2e 20 20 7b 41 31 37 30 32 38 7d 20 49 66 er. {A17028} If
36670 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 the same thread
36680 20 74 72 69 65 73 20 74 6f 20 65 6e 74 65 72 20 tries to enter
36690 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6b 69 6e any other.** kin
366a0 64 20 6f 66 20 6d 75 74 65 78 20 6d 6f 72 65 20 d of mutex more
366b0 74 68 61 6e 20 6f 6e 63 65 2c 20 74 68 65 20 62 than once, the b
366c0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 ehavior is undef
366d0 69 6e 65 64 2e 0a 2a 2a 20 7b 48 31 37 30 32 39 ined..** {H17029
366e0 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 } SQLite will ne
366f0 76 65 72 20 65 78 68 69 62 69 74 0a 2a 2a 20 73 ver exhibit.** s
36700 75 63 68 20 62 65 68 61 76 69 6f 72 20 69 6e 20 uch behavior in
36710 69 74 73 20 6f 77 6e 20 75 73 65 20 6f 66 20 6d its own use of m
36720 75 74 65 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 6f utexes..**.** So
36730 6d 65 20 73 79 73 74 65 6d 73 20 28 66 6f 72 20 me systems (for
36740 65 78 61 6d 70 6c 65 2c 20 57 69 6e 64 6f 77 73 example, Windows
36750 20 39 35 29 20 64 6f 20 6e 6f 74 20 73 75 70 70 95) do not supp
36760 6f 72 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f ort the operatio
36770 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 65 64 n.** implemented
36780 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 by sqlite3_mute
36790 78 5f 74 72 79 28 29 2e 20 20 4f 6e 20 74 68 6f x_try(). On tho
367a0 73 65 20 73 79 73 74 65 6d 73 2c 20 73 71 6c 69 se systems, sqli
367b0 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 0a te3_mutex_try().
367c0 2a 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 ** will always r
367d0 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 42 55 53 eturn SQLITE_BUS
367e0 59 2e 20 20 7b 48 31 37 30 33 30 7d 20 54 68 65 Y. {H17030} The
367f0 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6f 6e 6c SQLite core onl
36800 79 20 65 76 65 72 20 75 73 65 73 0a 2a 2a 20 73 y ever uses.** s
36810 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 qlite3_mutex_try
36820 28 29 20 61 73 20 61 6e 20 6f 70 74 69 6d 69 7a () as an optimiz
36830 61 74 69 6f 6e 20 73 6f 20 74 68 69 73 20 69 73 ation so this is
36840 20 61 63 63 65 70 74 61 62 6c 65 20 62 65 68 61 acceptable beha
36850 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 vior..**.** {H17
36860 30 33 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 031} The sqlite3
36870 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20 72 _mutex_leave() r
36880 6f 75 74 69 6e 65 20 65 78 69 74 73 20 61 20 6d outine exits a m
36890 75 74 65 78 20 74 68 61 74 20 77 61 73 0a 2a 2a utex that was.**
368a0 20 70 72 65 76 69 6f 75 73 6c 79 20 65 6e 74 65 previously ente
368b0 72 65 64 20 62 79 20 74 68 65 20 73 61 6d 65 20 red by the same
368c0 74 68 72 65 61 64 2e 20 20 7b 41 31 37 30 33 32 thread. {A17032
368d0 7d 20 54 68 65 20 62 65 68 61 76 69 6f 72 0a 2a } The behavior.*
368e0 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 69 * is undefined i
368f0 66 20 74 68 65 20 6d 75 74 65 78 20 69 73 20 6e f the mutex is n
36900 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 ot currently ent
36910 65 72 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 63 ered by the.** c
36920 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 6f 72 alling thread or
36930 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c is not currentl
36940 79 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 7b 48 y allocated. {H
36950 31 37 30 33 33 7d 20 53 51 4c 69 74 65 20 77 69 17033} SQLite wi
36960 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 64 6f 20 65 ll.** never do e
36970 69 74 68 65 72 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a ither. {END}.**.
36980 2a 2a 20 49 66 20 74 68 65 20 61 72 67 75 6d 65 ** If the argume
36990 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 nt to sqlite3_mu
369a0 74 65 78 5f 65 6e 74 65 72 28 29 2c 20 73 71 6c tex_enter(), sql
369b0 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 ite3_mutex_try()
369c0 2c 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f , or.** sqlite3_
369d0 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20 69 73 mutex_leave() is
369e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
369f0 20 74 68 65 6e 20 61 6c 6c 20 74 68 72 65 65 20 then all three
36a00 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 62 65 68 61 routines.** beha
36a10 76 65 20 61 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a ve as no-ops..**
36a20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
36a30 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c qlite3_mutex_hel
36a40 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 d()] and [sqlite
36a50 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 3_mutex_notheld(
36a60 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 )]..*/.SQLITE_AP
36a70 49 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 I sqlite3_mutex
36a80 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 *sqlite3_mutex_a
36a90 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54 lloc(int);.SQLIT
36aa0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 E_API void sqlit
36ab0 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 73 71 e3_mutex_free(sq
36ac0 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 53 lite3_mutex*);.S
36ad0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
36ae0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 qlite3_mutex_ent
36af0 65 72 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 er(sqlite3_mutex
36b00 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 *);.SQLITE_API i
36b10 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 nt sqlite3_mutex
36b20 5f 74 72 79 28 73 71 6c 69 74 65 33 5f 6d 75 74 _try(sqlite3_mut
36b30 65 78 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ex*);.SQLITE_API
36b40 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 void sqlite3_mu
36b50 74 65 78 5f 6c 65 61 76 65 28 73 71 6c 69 74 65 tex_leave(sqlite
36b60 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 3_mutex*);../*.*
36b70 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 * CAPI3REF: Mute
36b80 78 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 x Methods Object
36b90 20 7b 48 31 37 31 32 30 7d 20 3c 53 32 30 31 33 {H17120} <S2013
36ba0 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 0>.** EXPERIMENT
36bb0 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 AL.**.** An inst
36bc0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 ance of this str
36bd0 75 63 74 75 72 65 20 64 65 66 69 6e 65 73 20 74 ucture defines t
36be0 68 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 72 6f 75 he low-level rou
36bf0 74 69 6e 65 73 0a 2a 2a 20 75 73 65 64 20 74 6f tines.** used to
36c00 20 61 6c 6c 6f 63 61 74 65 20 61 6e 64 20 75 73 allocate and us
36c10 65 20 6d 75 74 65 78 65 73 2e 0a 2a 2a 0a 2a 2a e mutexes..**.**
36c20 20 55 73 75 61 6c 6c 79 2c 20 74 68 65 20 64 65 Usually, the de
36c30 66 61 75 6c 74 20 6d 75 74 65 78 20 69 6d 70 6c fault mutex impl
36c40 65 6d 65 6e 74 61 74 69 6f 6e 73 20 70 72 6f 76 ementations prov
36c50 69 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 ided by SQLite a
36c60 72 65 0a 2a 2a 20 73 75 66 66 69 63 69 65 6e 74 re.** sufficient
36c70 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 75 73 , however the us
36c80 65 72 20 68 61 73 20 74 68 65 20 6f 70 74 69 6f er has the optio
36c90 6e 20 6f 66 20 73 75 62 73 74 69 74 75 74 69 6e n of substitutin
36ca0 67 20 61 20 63 75 73 74 6f 6d 0a 2a 2a 20 69 6d g a custom.** im
36cb0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 plementation for
36cc0 20 73 70 65 63 69 61 6c 69 7a 65 64 20 64 65 70 specialized dep
36cd0 6c 6f 79 6d 65 6e 74 73 20 6f 72 20 73 79 73 74 loyments or syst
36ce0 65 6d 73 20 66 6f 72 20 77 68 69 63 68 20 53 51 ems for which SQ
36cf0 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 Lite.** does not
36d00 20 70 72 6f 76 69 64 65 20 61 20 73 75 69 74 61 provide a suita
36d10 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ble implementati
36d20 6f 6e 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 on. In this case
36d30 2c 20 74 68 65 20 75 73 65 72 0a 2a 2a 20 63 72 , the user.** cr
36d40 65 61 74 65 73 20 61 6e 64 20 70 6f 70 75 6c 61 eates and popula
36d50 74 65 73 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 tes an instance
36d60 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 of this structur
36d70 65 20 74 6f 20 70 61 73 73 0a 2a 2a 20 74 6f 20 e to pass.** to
36d80 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
36d90 20 61 6c 6f 6e 67 20 77 69 74 68 20 74 68 65 20 along with the
36da0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
36db0 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a 2a 2a UTEX] option..**
36dc0 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 61 Additionally, a
36dd0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
36de0 69 73 20 73 74 72 75 63 74 75 72 65 20 63 61 6e is structure can
36df0 20 62 65 20 75 73 65 64 20 61 73 20 61 6e 0a 2a be used as an.*
36e00 2a 20 6f 75 74 70 75 74 20 76 61 72 69 61 62 6c * output variabl
36e10 65 20 77 68 65 6e 20 71 75 65 72 79 69 6e 67 20 e when querying
36e20 74 68 65 20 73 79 73 74 65 6d 20 66 6f 72 20 74 the system for t
36e30 68 65 20 63 75 72 72 65 6e 74 20 6d 75 74 65 78 he current mutex
36e40 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
36e50 6f 6e 2c 20 75 73 69 6e 67 20 74 68 65 20 5b 53 on, using the [S
36e60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
36e70 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a 2a MUTEX] option..*
36e80 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74 65 78 49 *.** The xMutexI
36e90 6e 69 74 20 6d 65 74 68 6f 64 20 64 65 66 69 6e nit method defin
36ea0 65 64 20 62 79 20 74 68 69 73 20 73 74 72 75 63 ed by this struc
36eb0 74 75 72 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 ture is invoked
36ec0 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 73 79 as.** part of sy
36ed0 73 74 65 6d 20 69 6e 69 74 69 61 6c 69 7a 61 74 stem initializat
36ee0 69 6f 6e 20 62 79 20 74 68 65 20 73 71 6c 69 74 ion by the sqlit
36ef0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
36f00 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 7b 48 31 function..** {H1
36f10 37 30 30 31 7d 20 54 68 65 20 78 4d 75 74 65 78 7001} The xMutex
36f20 49 6e 69 74 20 72 6f 75 74 69 6e 65 20 73 68 61 Init routine sha
36f30 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 79 20 ll be called by
36f40 53 51 4c 69 74 65 20 6f 6e 63 65 20 66 6f 72 20 SQLite once for
36f50 65 61 63 68 0a 2a 2a 20 65 66 66 65 63 74 69 76 each.** effectiv
36f60 65 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 e call to [sqlit
36f70 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d e3_initialize()]
36f80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74 ..**.** The xMut
36f90 65 78 45 6e 64 20 6d 65 74 68 6f 64 20 64 65 66 exEnd method def
36fa0 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 74 72 ined by this str
36fb0 75 63 74 75 72 65 20 69 73 20 69 6e 76 6f 6b 65 ucture is invoke
36fc0 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 d as.** part of
36fd0 73 79 73 74 65 6d 20 73 68 75 74 64 6f 77 6e 20 system shutdown
36fe0 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 by the sqlite3_s
36ff0 68 75 74 64 6f 77 6e 28 29 20 66 75 6e 63 74 69 hutdown() functi
37000 6f 6e 2e 20 54 68 65 0a 2a 2a 20 69 6d 70 6c 65 on. The.** imple
37010 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 69 mentation of thi
37020 73 20 6d 65 74 68 6f 64 20 69 73 20 65 78 70 65 s method is expe
37030 63 74 65 64 20 74 6f 20 72 65 6c 65 61 73 65 20 cted to release
37040 61 6c 6c 20 6f 75 74 73 74 61 6e 64 69 6e 67 0a all outstanding.
37050 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 6f 62 74 ** resources obt
37060 61 69 6e 65 64 20 62 79 20 74 68 65 20 6d 75 74 ained by the mut
37070 65 78 20 6d 65 74 68 6f 64 73 20 69 6d 70 6c 65 ex methods imple
37080 6d 65 6e 74 61 74 69 6f 6e 2c 20 65 73 70 65 63 mentation, espec
37090 69 61 6c 6c 79 0a 2a 2a 20 74 68 6f 73 65 20 6f ially.** those o
370a0 62 74 61 69 6e 65 64 20 62 79 20 74 68 65 20 78 btained by the x
370b0 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 MutexInit method
370c0 2e 20 7b 48 31 37 30 30 33 7d 20 54 68 65 20 78 . {H17003} The x
370d0 4d 75 74 65 78 45 6e 64 28 29 0a 2a 2a 20 69 6e MutexEnd().** in
370e0 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 62 65 terface shall be
370f0 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f invoked once fo
37100 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b r each call to [
37110 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
37120 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 ()]..**.** The r
37130 65 6d 61 69 6e 69 6e 67 20 73 65 76 65 6e 20 6d emaining seven m
37140 65 74 68 6f 64 73 20 64 65 66 69 6e 65 64 20 62 ethods defined b
37150 79 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 y this structure
37160 20 28 78 4d 75 74 65 78 41 6c 6c 6f 63 2c 0a 2a (xMutexAlloc,.*
37170 2a 20 78 4d 75 74 65 78 46 72 65 65 2c 20 78 4d * xMutexFree, xM
37180 75 74 65 78 45 6e 74 65 72 2c 20 78 4d 75 74 65 utexEnter, xMute
37190 78 54 72 79 2c 20 78 4d 75 74 65 78 4c 65 61 76 xTry, xMutexLeav
371a0 65 2c 20 78 4d 75 74 65 78 48 65 6c 64 20 61 6e e, xMutexHeld an
371b0 64 0a 2a 2a 20 78 4d 75 74 65 78 4e 6f 74 68 65 d.** xMutexNothe
371c0 6c 64 29 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 ld) implement th
371d0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 e following inte
371e0 72 66 61 63 65 73 20 28 72 65 73 70 65 63 74 69 rfaces (respecti
371f0 76 65 6c 79 29 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c vely):.**.** <ul
37200 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 >.** <li> [sq
37210 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f lite3_mutex_allo
37220 63 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 c()] </li>.**
37230 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d <li> [sqlite3_m
37240 75 74 65 78 5f 66 72 65 65 28 29 5d 20 3c 2f 6c utex_free()] </l
37250 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 i>.** <li> [s
37260 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 qlite3_mutex_ent
37270 65 72 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 er()] </li>.**
37280 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f <li> [sqlite3_
37290 6d 75 74 65 78 5f 74 72 79 28 29 5d 20 3c 2f 6c mutex_try()] </l
372a0 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 i>.** <li> [s
372b0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 qlite3_mutex_lea
372c0 76 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 ve()] </li>.**
372d0 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f <li> [sqlite3_
372e0 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 3c 2f mutex_held()] </
372f0 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b li>.** <li> [
37300 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f sqlite3_mutex_no
37310 74 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a theld()] </li>.*
37320 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 * </ul>.**.** Th
37330 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 e only differenc
37340 65 20 69 73 20 74 68 61 74 20 74 68 65 20 70 75 e is that the pu
37350 62 6c 69 63 20 73 71 6c 69 74 65 33 5f 58 58 58 blic sqlite3_XXX
37360 20 66 75 6e 63 74 69 6f 6e 73 20 65 6e 75 6d 65 functions enume
37370 72 61 74 65 64 0a 2a 2a 20 61 62 6f 76 65 20 73 rated.** above s
37380 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 61 ilently ignore a
37390 6e 79 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 74 ny invocations t
373a0 68 61 74 20 70 61 73 73 20 61 20 4e 55 4c 4c 20 hat pass a NULL
373b0 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 0a pointer instead.
373c0 2a 2a 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 ** of a valid mu
373d0 74 65 78 20 68 61 6e 64 6c 65 2e 20 54 68 65 20 tex handle. The
373e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
373f0 6f 66 20 74 68 65 20 6d 65 74 68 6f 64 73 20 64 of the methods d
37400 65 66 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69 efined.** by thi
37410 73 20 73 74 72 75 63 74 75 72 65 20 61 72 65 20 s structure are
37420 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 not required to
37430 68 61 6e 64 6c 65 20 74 68 69 73 20 63 61 73 65 handle this case
37440 2c 20 74 68 65 20 72 65 73 75 6c 74 73 0a 2a 2a , the results.**
37450 20 6f 66 20 70 61 73 73 69 6e 67 20 61 20 4e 55 of passing a NU
37460 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 LL pointer inste
37470 61 64 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 ad of a valid mu
37480 74 65 78 20 68 61 6e 64 6c 65 20 61 72 65 20 75 tex handle are u
37490 6e 64 65 66 69 6e 65 64 0a 2a 2a 20 28 69 2e 65 ndefined.** (i.e
374a0 2e 20 69 74 20 69 73 20 61 63 63 65 70 74 61 62 . it is acceptab
374b0 6c 65 20 74 6f 20 70 72 6f 76 69 64 65 20 61 6e le to provide an
374c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
374d0 74 68 61 74 20 73 65 67 66 61 75 6c 74 73 20 69 that segfaults i
374e0 66 0a 2a 2a 20 69 74 20 69 73 20 70 61 73 73 65 f.** it is passe
374f0 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 d a NULL pointer
37500 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 )..**.** The xMu
37510 74 65 78 49 6e 69 74 28 29 20 6d 65 74 68 6f 64 texInit() method
37520 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 must be threads
37530 61 66 65 2e 20 20 49 74 20 6d 75 73 74 20 62 65 afe. It must be
37540 20 68 61 72 6d 6c 65 73 73 20 74 6f 0a 2a 2a 20 harmless to.**
37550 69 6e 76 6f 6b 65 20 78 4d 75 74 65 78 49 6e 69 invoke xMutexIni
37560 74 28 29 20 6d 75 74 69 70 6c 65 20 74 69 6d 65 t() mutiple time
37570 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d s within the sam
37580 65 20 70 72 6f 63 65 73 73 20 61 6e 64 20 77 69 e process and wi
37590 74 68 6f 75 74 0a 2a 2a 20 69 6e 74 65 72 76 65 thout.** interve
375a0 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 78 4d ning calls to xM
375b0 75 74 65 78 45 6e 64 28 29 2e 20 20 53 65 63 6f utexEnd(). Seco
375c0 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e nd and subsequen
375d0 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 78 4d t calls to.** xM
375e0 75 74 65 78 49 6e 69 74 28 29 20 6d 75 73 74 20 utexInit() must
375f0 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a be no-ops..**.**
37600 20 78 4d 75 74 65 78 49 6e 69 74 28 29 20 6d 75 xMutexInit() mu
37610 73 74 20 6e 6f 74 20 75 73 65 20 53 51 4c 69 74 st not use SQLit
37620 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
37630 69 6f 6e 20 28 5b 73 71 6c 69 74 65 33 5f 6d 61 ion ([sqlite3_ma
37640 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 61 6e 64 20 69 lloc()].** and i
37650 74 73 20 61 73 73 6f 63 69 61 74 65 73 29 2e 20 ts associates).
37660 20 53 69 6d 69 6c 61 72 6c 79 2c 20 78 4d 75 74 Similarly, xMut
37670 65 78 41 6c 6c 6f 63 28 29 20 6d 75 73 74 20 6e exAlloc() must n
37680 6f 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d 65 ot use SQLite me
37690 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 mory.** allocati
376a0 6f 6e 20 66 6f 72 20 61 20 73 74 61 74 69 63 20 on for a static
376b0 6d 75 74 65 78 2e 20 20 48 6f 77 65 76 65 72 20 mutex. However
376c0 78 4d 75 74 65 78 41 6c 6c 6f 63 28 29 20 6d 61 xMutexAlloc() ma
376d0 79 20 75 73 65 20 53 51 4c 69 74 65 0a 2a 2a 20 y use SQLite.**
376e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
376f0 6e 20 66 6f 72 20 61 20 66 61 73 74 20 6f 72 20 n for a fast or
37700 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 2e recursive mutex.
37710 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 .**.** SQLite wi
37720 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 78 4d ll invoke the xM
37730 75 74 65 78 45 6e 64 28 29 20 6d 65 74 68 6f 64 utexEnd() method
37740 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 when [sqlite3_s
37750 68 75 74 64 6f 77 6e 28 29 5d 20 69 73 0a 2a 2a hutdown()] is.**
37760 20 63 61 6c 6c 65 64 2c 20 62 75 74 20 6f 6e 6c called, but onl
37770 79 20 69 66 20 74 68 65 20 70 72 69 6f 72 20 63 y if the prior c
37780 61 6c 6c 20 74 6f 20 78 4d 75 74 65 78 49 6e 69 all to xMutexIni
37790 74 20 72 65 74 75 72 6e 65 64 20 53 51 4c 49 54 t returned SQLIT
377a0 45 5f 4f 4b 2e 0a 2a 2a 20 49 66 20 78 4d 75 74 E_OK..** If xMut
377b0 65 78 49 6e 69 74 20 66 61 69 6c 73 20 69 6e 20 exInit fails in
377c0 61 6e 79 20 77 61 79 2c 20 69 74 20 69 73 20 65 any way, it is e
377d0 78 70 65 63 74 65 64 20 74 6f 20 63 6c 65 61 6e xpected to clean
377e0 20 75 70 20 61 66 74 65 72 20 69 74 73 65 6c 66 up after itself
377f0 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 72 65 74 .** prior to ret
37800 75 72 6e 69 6e 67 2e 0a 2a 2f 0a 74 79 70 65 64 urning..*/.typed
37810 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
37820 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 20 3_mutex_methods
37830 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 sqlite3_mutex_me
37840 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 thods;.struct sq
37850 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 lite3_mutex_meth
37860 6f 64 73 20 7b 0a 20 20 69 6e 74 20 28 2a 78 4d ods {. int (*xM
37870 75 74 65 78 49 6e 69 74 29 28 76 6f 69 64 29 3b utexInit)(void);
37880 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 45 . int (*xMutexE
37890 6e 64 29 28 76 6f 69 64 29 3b 0a 20 20 73 71 6c nd)(void);. sql
378a0 69 74 65 33 5f 6d 75 74 65 78 20 2a 28 2a 78 4d ite3_mutex *(*xM
378b0 75 74 65 78 41 6c 6c 6f 63 29 28 69 6e 74 29 3b utexAlloc)(int);
378c0 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 74 65 78 . void (*xMutex
378d0 46 72 65 65 29 28 73 71 6c 69 74 65 33 5f 6d 75 Free)(sqlite3_mu
378e0 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28 tex *);. void (
378f0 2a 78 4d 75 74 65 78 45 6e 74 65 72 29 28 73 71 *xMutexEnter)(sq
37900 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a lite3_mutex *);.
37910 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 54 72 int (*xMutexTr
37920 79 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 y)(sqlite3_mutex
37930 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d *);. void (*xM
37940 75 74 65 78 4c 65 61 76 65 29 28 73 71 6c 69 74 utexLeave)(sqlit
37950 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 69 e3_mutex *);. i
37960 6e 74 20 28 2a 78 4d 75 74 65 78 48 65 6c 64 29 nt (*xMutexHeld)
37970 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a (sqlite3_mutex *
37980 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 );. int (*xMute
37990 78 4e 6f 74 68 65 6c 64 29 28 73 71 6c 69 74 65 xNotheld)(sqlite
379a0 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 7d 3b 0a 0a 3_mutex *);.};..
379b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
379c0 4d 75 74 65 78 20 56 65 72 69 66 69 63 61 74 69 Mutex Verificati
379d0 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b 48 31 37 on Routines {H17
379e0 30 38 30 7d 20 3c 53 32 30 31 33 30 3e 20 3c 53 080} <S20130> <S
379f0 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 30800>.**.** The
37a00 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 sqlite3_mutex_h
37a10 65 6c 64 28 29 20 61 6e 64 20 73 71 6c 69 74 65 eld() and sqlite
37a20 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 3_mutex_notheld(
37a30 29 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 ) routines.** ar
37a40 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 e intended for u
37a50 73 65 20 69 6e 73 69 64 65 20 61 73 73 65 72 74 se inside assert
37a60 28 29 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 7b () statements. {
37a70 48 31 37 30 38 31 7d 20 54 68 65 20 53 51 4c 69 H17081} The SQLi
37a80 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 65 72 te core.** never
37a90 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 uses these rout
37aa0 69 6e 65 73 20 65 78 63 65 70 74 20 69 6e 73 69 ines except insi
37ab0 64 65 20 61 6e 20 61 73 73 65 72 74 28 29 20 61 de an assert() a
37ac0 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a nd applications.
37ad0 2a 2a 20 61 72 65 20 61 64 76 69 73 65 64 20 74 ** are advised t
37ae0 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c 65 61 o follow the lea
37af0 64 20 6f 66 20 74 68 65 20 63 6f 72 65 2e 20 20 d of the core.
37b00 7b 48 31 37 30 38 32 7d 20 54 68 65 20 63 6f 72 {H17082} The cor
37b10 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69 64 e only.** provid
37b20 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f es implementatio
37b30 6e 73 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 ns for these rou
37b40 74 69 6e 65 73 20 77 68 65 6e 20 69 74 20 69 73 tines when it is
37b50 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 compiled.** wit
37b60 68 20 74 68 65 20 53 51 4c 49 54 45 5f 44 45 42 h the SQLITE_DEB
37b70 55 47 20 66 6c 61 67 2e 20 20 7b 41 31 37 30 38 UG flag. {A1708
37b80 37 7d 20 45 78 74 65 72 6e 61 6c 20 6d 75 74 65 7} External mute
37b90 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e x implementation
37ba0 73 0a 2a 2a 20 61 72 65 20 6f 6e 6c 79 20 72 65 s.** are only re
37bb0 71 75 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64 quired to provid
37bc0 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 e these routines
37bd0 20 69 66 20 53 51 4c 49 54 45 5f 44 45 42 55 47 if SQLITE_DEBUG
37be0 20 69 73 0a 2a 2a 20 64 65 66 69 6e 65 64 20 61 is.** defined a
37bf0 6e 64 20 69 66 20 4e 44 45 42 55 47 20 69 73 20 nd if NDEBUG is
37c00 6e 6f 74 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a not defined..**.
37c10 2a 2a 20 7b 48 31 37 30 38 33 7d 20 54 68 65 73 ** {H17083} Thes
37c20 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c e routines shoul
37c30 64 20 72 65 74 75 72 6e 20 74 72 75 65 20 69 66 d return true if
37c40 20 74 68 65 20 6d 75 74 65 78 20 69 6e 20 74 68 the mutex in th
37c50 65 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 eir argument.**
37c60 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20 68 is held or not h
37c70 65 6c 64 2c 20 72 65 73 70 65 63 74 69 76 65 6c eld, respectivel
37c80 79 2c 20 62 79 20 74 68 65 20 63 61 6c 6c 69 6e y, by the callin
37c90 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 g thread..**.**
37ca0 7b 58 31 37 30 38 34 7d 20 54 68 65 20 69 6d 70 {X17084} The imp
37cb0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e lementation is n
37cc0 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 70 ot required to p
37cd0 72 6f 76 69 64 65 64 20 76 65 72 73 69 6f 6e 73 rovided versions
37ce0 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 72 6f 75 of these.** rou
37cf0 74 69 6e 65 73 20 74 68 61 74 20 61 63 74 75 61 tines that actua
37d00 6c 6c 79 20 77 6f 72 6b 2e 20 49 66 20 74 68 65 lly work. If the
37d10 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
37d20 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 does not provide
37d30 20 77 6f 72 6b 69 6e 67 0a 2a 2a 20 76 65 72 73 working.** vers
37d40 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 20 72 6f ions of these ro
37d50 75 74 69 6e 65 73 2c 20 69 74 20 73 68 6f 75 6c utines, it shoul
37d60 64 20 61 74 20 6c 65 61 73 74 20 70 72 6f 76 69 d at least provi
37d70 64 65 20 73 74 75 62 73 20 74 68 61 74 20 61 6c de stubs that al
37d80 77 61 79 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74 ways.** return t
37d90 72 75 65 20 73 6f 20 74 68 61 74 20 6f 6e 65 20 rue so that one
37da0 64 6f 65 73 20 6e 6f 74 20 67 65 74 20 73 70 75 does not get spu
37db0 72 69 6f 75 73 20 61 73 73 65 72 74 69 6f 6e 20 rious assertion
37dc0 66 61 69 6c 75 72 65 73 2e 0a 2a 2a 0a 2a 2a 20 failures..**.**
37dd0 7b 48 31 37 30 38 35 7d 20 49 66 20 74 68 65 20 {H17085} If the
37de0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
37df0 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 te3_mutex_held()
37e00 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
37e10 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 er then.** the r
37e20 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 72 65 outine should re
37e30 74 75 72 6e 20 31 2e 20 20 7b 45 4e 44 7d 20 54 turn 1. {END} T
37e40 68 69 73 20 73 65 65 6d 73 20 63 6f 75 6e 74 65 his seems counte
37e50 72 2d 69 6e 74 75 69 74 69 76 65 20 73 69 6e 63 r-intuitive sinc
37e60 65 0a 2a 2a 20 63 6c 65 61 72 6c 79 20 74 68 65 e.** clearly the
37e70 20 6d 75 74 65 78 20 63 61 6e 6e 6f 74 20 62 65 mutex cannot be
37e80 20 68 65 6c 64 20 69 66 20 69 74 20 64 6f 65 73 held if it does
37e90 20 6e 6f 74 20 65 78 69 73 74 2e 20 20 42 75 74 not exist. But
37ea0 20 74 68 65 0a 2a 2a 20 74 68 65 20 72 65 61 73 the.** the reas
37eb0 6f 6e 20 74 68 65 20 6d 75 74 65 78 20 64 6f 65 on the mutex doe
37ec0 73 20 6e 6f 74 20 65 78 69 73 74 20 69 73 20 62 s not exist is b
37ed0 65 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 64 ecause the build
37ee0 20 69 73 20 6e 6f 74 0a 2a 2a 20 75 73 69 6e 67 is not.** using
37ef0 20 6d 75 74 65 78 65 73 2e 20 20 41 6e 64 20 77 mutexes. And w
37f00 65 20 64 6f 20 6e 6f 74 20 77 61 6e 74 20 74 68 e do not want th
37f10 65 20 61 73 73 65 72 74 28 29 20 63 6f 6e 74 61 e assert() conta
37f20 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 61 6c ining the.** cal
37f30 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 l to sqlite3_mut
37f40 65 78 5f 68 65 6c 64 28 29 20 74 6f 20 66 61 69 ex_held() to fai
37f50 6c 2c 20 73 6f 20 61 20 6e 6f 6e 2d 7a 65 72 6f l, so a non-zero
37f60 20 72 65 74 75 72 6e 20 69 73 0a 2a 2a 20 74 68 return is.** th
37f70 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 74 68 e appropriate th
37f80 69 6e 67 20 74 6f 20 64 6f 2e 20 20 7b 48 31 37 ing to do. {H17
37f90 30 38 36 7d 20 54 68 65 20 73 71 6c 69 74 65 33 086} The sqlite3
37fa0 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 _mutex_notheld()
37fb0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 73 68 .** interface sh
37fc0 6f 75 6c 64 20 61 6c 73 6f 20 72 65 74 75 72 6e ould also return
37fd0 20 31 20 77 68 65 6e 20 67 69 76 65 6e 20 61 20 1 when given a
37fe0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f NULL pointer..*/
37ff0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
38000 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 sqlite3_mutex_he
38010 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 ld(sqlite3_mutex
38020 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 *);.SQLITE_API i
38030 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 nt sqlite3_mutex
38040 5f 6e 6f 74 68 65 6c 64 28 73 71 6c 69 74 65 33 _notheld(sqlite3
38050 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a _mutex*);../*.**
38060 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 CAPI3REF: Mutex
38070 20 54 79 70 65 73 20 7b 48 31 37 30 30 31 7d 20 Types {H17001}
38080 3c 48 31 37 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <H17000>.**.** T
38090 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 he [sqlite3_mute
380a0 78 5f 61 6c 6c 6f 63 28 29 5d 20 69 6e 74 65 72 x_alloc()] inter
380b0 66 61 63 65 20 74 61 6b 65 73 20 61 20 73 69 6e face takes a sin
380c0 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 gle argument.**
380d0 77 68 69 63 68 20 69 73 20 6f 6e 65 20 6f 66 20 which is one of
380e0 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f these integer co
380f0 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 nstants..**.** T
38100 68 65 20 73 65 74 20 6f 66 20 73 74 61 74 69 63 he set of static
38110 20 6d 75 74 65 78 65 73 20 6d 61 79 20 63 68 61 mutexes may cha
38120 6e 67 65 20 66 72 6f 6d 20 6f 6e 65 20 53 51 4c nge from one SQL
38130 69 74 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 ite release to t
38140 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 he.** next. App
38150 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6f lications that o
38160 76 65 72 72 69 64 65 20 74 68 65 20 62 75 69 6c verride the buil
38170 74 2d 69 6e 20 6d 75 74 65 78 20 6c 6f 67 69 63 t-in mutex logic
38180 20 6d 75 73 74 20 62 65 0a 2a 2a 20 70 72 65 70 must be.** prep
38190 61 72 65 64 20 74 6f 20 61 63 63 6f 6d 6d 6f 64 ared to accommod
381a0 61 74 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 ate additional s
381b0 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e 0a 2a tatic mutexes..*
381c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
381d0 5f 4d 55 54 45 58 5f 46 41 53 54 20 20 20 20 20 _MUTEX_FAST
381e0 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 0.#defin
381f0 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 e SQLITE_MUTEX_R
38200 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20 20 ECURSIVE
38210 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
38220 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 _MUTEX_STATIC_MA
38230 53 54 45 52 20 20 20 20 32 0a 23 64 65 66 69 6e STER 2.#defin
38240 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 e SQLITE_MUTEX_S
38250 54 41 54 49 43 5f 4d 45 4d 20 20 20 20 20 20 20 TATIC_MEM
38260 33 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 61 3 /* sqlite3_ma
38270 6c 6c 6f 63 28 29 20 2a 2f 0a 23 64 65 66 69 6e lloc() */.#defin
38280 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 e SQLITE_MUTEX_S
38290 54 41 54 49 43 5f 4d 45 4d 32 20 20 20 20 20 20 TATIC_MEM2
382a0 34 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 20 2a 4 /* NOT USED *
382b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
382c0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4f 50 _MUTEX_STATIC_OP
382d0 45 4e 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 EN 4 /* sq
382e0 6c 69 74 65 33 42 74 72 65 65 4f 70 65 6e 28 29 lite3BtreeOpen()
382f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
38300 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
38310 50 52 4e 47 20 20 20 20 20 20 35 20 20 2f 2a 20 PRNG 5 /*
38320 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 28 29 sqlite3_random()
38330 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
38340 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
38350 4c 52 55 20 20 20 20 20 20 20 36 20 20 2f 2a 20 LRU 6 /*
38360 6c 72 75 20 70 61 67 65 20 6c 69 73 74 20 2a 2f lru page list */
38370 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
38380 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 MUTEX_STATIC_LRU
38390 32 20 20 20 20 20 20 37 20 20 2f 2a 20 6c 72 75 2 7 /* lru
383a0 20 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a 0a 2f page list */../
383b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
383c0 65 74 72 69 65 76 65 20 74 68 65 20 6d 75 74 65 etrieve the mute
383d0 78 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 x for a database
383e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 37 connection {H17
383f0 30 30 32 7d 20 3c 48 31 37 30 30 30 3e 0a 2a 2a 002} <H17000>.**
38400 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 .** This interfa
38410 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 ce returns a poi
38420 6e 74 65 72 20 74 68 65 20 5b 73 71 6c 69 74 65 nter the [sqlite
38430 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 20 3_mutex] object
38440 74 68 61 74 20 0a 2a 2a 20 73 65 72 69 61 6c 69 that .** seriali
38450 7a 65 73 20 61 63 63 65 73 73 20 74 6f 20 74 68 zes access to th
38460 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
38470 65 63 74 69 6f 6e 5d 20 67 69 76 65 6e 20 69 6e ection] given in
38480 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a the argument.**
38490 20 77 68 65 6e 20 74 68 65 20 5b 74 68 72 65 61 when the [threa
384a0 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 53 65 ding mode] is Se
384b0 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 49 66 20 rialized..** If
384c0 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d the [threading m
384d0 6f 64 65 5d 20 69 73 20 53 69 6e 67 6c 65 2d 74 ode] is Single-t
384e0 68 72 65 61 64 20 6f 72 20 4d 75 6c 74 69 2d 74 hread or Multi-t
384f0 68 72 65 61 64 20 74 68 65 6e 20 74 68 69 73 0a hread then this.
38500 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 ** routine retur
38510 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ns a NULL pointe
38520 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 r..*/.SQLITE_API
38530 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a sqlite3_mutex *
38540 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 sqlite3_db_mutex
38550 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
38560 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 77 ** CAPI3REF: Low
38570 2d 4c 65 76 65 6c 20 43 6f 6e 74 72 6f 6c 20 4f -Level Control O
38580 66 20 44 61 74 61 62 61 73 65 20 46 69 6c 65 73 f Database Files
38590 20 7b 48 31 31 33 30 30 7d 20 3c 53 33 30 38 30 {H11300} <S3080
385a0 30 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 31 0>.**.** {H11301
385b0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 } The [sqlite3_f
385c0 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 ile_control()] i
385d0 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 nterface makes a
385e0 20 64 69 72 65 63 74 20 63 61 6c 6c 20 74 6f 20 direct call to
385f0 74 68 65 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 the.** xFileCont
38600 72 6f 6c 20 6d 65 74 68 6f 64 20 66 6f 72 20 74 rol method for t
38610 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d he [sqlite3_io_m
38620 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 ethods] object a
38630 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 ssociated.** wit
38640 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 h a particular d
38650 61 74 61 62 61 73 65 20 69 64 65 6e 74 69 66 69 atabase identifi
38660 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 ed by the second
38670 20 61 72 67 75 6d 65 6e 74 2e 20 7b 48 31 31 33 argument. {H113
38680 30 32 7d 20 54 68 65 0a 2a 2a 20 6e 61 6d 65 20 02} The.** name
38690 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 of the database
386a0 69 73 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 is the name assi
386b0 67 6e 65 64 20 74 6f 20 74 68 65 20 64 61 74 61 gned to the data
386c0 62 61 73 65 20 62 79 20 74 68 65 0a 2a 2a 20 3c base by the.** <
386d0 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f 61 74 74 a href="lang_att
386e0 61 63 68 2e 68 74 6d 6c 22 3e 41 54 54 41 43 48 ach.html">ATTACH
386f0 3c 2f 61 3e 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 </a> SQL command
38700 20 74 68 61 74 20 6f 70 65 6e 65 64 20 74 68 65 that opened the
38710 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 7b 48 .** database. {H
38720 31 31 33 30 33 7d 20 54 6f 20 63 6f 6e 74 72 6f 11303} To contro
38730 6c 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 l the main datab
38740 61 73 65 20 66 69 6c 65 2c 20 75 73 65 20 74 68 ase file, use th
38750 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 0a 2a 2a e name "main".**
38760 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 or a NULL point
38770 65 72 2e 20 7b 48 31 31 33 30 34 7d 20 54 68 65 er. {H11304} The
38780 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 third and fourt
38790 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 h parameters to
387a0 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 this routine.**
387b0 61 72 65 20 70 61 73 73 65 64 20 64 69 72 65 63 are passed direc
387c0 74 6c 79 20 74 68 72 6f 75 67 68 20 74 6f 20 74 tly through to t
387d0 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 he second and th
387e0 69 72 64 20 70 61 72 61 6d 65 74 65 72 73 20 6f ird parameters o
387f0 66 0a 2a 2a 20 74 68 65 20 78 46 69 6c 65 43 6f f.** the xFileCo
38800 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 20 7b ntrol method. {
38810 48 31 31 33 30 35 7d 20 54 68 65 20 72 65 74 75 H11305} The retu
38820 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 rn value of the
38830 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 0a 2a 2a 20 xFileControl.**
38840 6d 65 74 68 6f 64 20 62 65 63 6f 6d 65 73 20 74 method becomes t
38850 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
38860 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e of this routine.
38870 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 36 7d 20 .**.** {H11306}
38880 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 If the second pa
38890 72 61 6d 65 74 65 72 20 28 7a 44 62 4e 61 6d 65 rameter (zDbName
388a0 29 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 ) does not match
388b0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 6e 79 the name of any
388c0 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61 62 61 73 .** open databas
388d0 65 20 66 69 6c 65 2c 20 74 68 65 6e 20 53 51 4c e file, then SQL
388e0 49 54 45 5f 45 52 52 4f 52 20 69 73 20 72 65 74 ITE_ERROR is ret
388f0 75 72 6e 65 64 2e 20 7b 48 31 31 33 30 37 7d 20 urned. {H11307}
38900 54 68 69 73 20 65 72 72 6f 72 0a 2a 2a 20 63 6f This error.** co
38910 64 65 20 69 73 20 6e 6f 74 20 72 65 6d 65 6d 62 de is not rememb
38920 65 72 65 64 20 61 6e 64 20 77 69 6c 6c 20 6e 6f ered and will no
38930 74 20 62 65 20 72 65 63 61 6c 6c 65 64 20 62 79 t be recalled by
38940 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 [sqlite3_errcod
38950 65 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 e()].** or [sqli
38960 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 20 7b te3_errmsg()]. {
38970 41 31 31 33 30 38 7d 20 54 68 65 20 75 6e 64 65 A11308} The unde
38980 72 6c 79 69 6e 67 20 78 46 69 6c 65 43 6f 6e 74 rlying xFileCont
38990 72 6f 6c 20 6d 65 74 68 6f 64 20 6d 69 67 68 74 rol method might
389a0 0a 2a 2a 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 .** also return
389b0 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 7b SQLITE_ERROR. {
389c0 41 31 31 33 30 39 7d 20 54 68 65 72 65 20 69 73 A11309} There is
389d0 20 6e 6f 20 77 61 79 20 74 6f 20 64 69 73 74 69 no way to disti
389e0 6e 67 75 69 73 68 20 62 65 74 77 65 65 6e 0a 2a nguish between.*
389f0 2a 20 61 6e 20 69 6e 63 6f 72 72 65 63 74 20 7a * an incorrect z
38a00 44 62 4e 61 6d 65 20 61 6e 64 20 61 6e 20 53 51 DbName and an SQ
38a10 4c 49 54 45 5f 45 52 52 4f 52 20 72 65 74 75 72 LITE_ERROR retur
38a20 6e 20 66 72 6f 6d 20 74 68 65 20 75 6e 64 65 72 n from the under
38a30 6c 79 69 6e 67 0a 2a 2a 20 78 46 69 6c 65 43 6f lying.** xFileCo
38a40 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 7b 45 ntrol method. {E
38a50 4e 44 7d 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c ND}.**.** See al
38a60 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 so: [SQLITE_FCNT
38a70 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 0a 2a 2f 0a L_LOCKSTATE].*/.
38a80 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
38a90 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
38aa0 72 6f 6c 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f rol(sqlite3*, co
38ab0 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d nst char *zDbNam
38ac0 65 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 2a e, int op, void*
38ad0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
38ae0 45 46 3a 20 54 65 73 74 69 6e 67 20 49 6e 74 65 EF: Testing Inte
38af0 72 66 61 63 65 20 7b 48 31 31 34 30 30 7d 20 3c rface {H11400} <
38b00 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S30800>.**.** Th
38b10 65 20 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 e sqlite3_test_c
38b20 6f 6e 74 72 6f 6c 28 29 20 69 6e 74 65 72 66 61 ontrol() interfa
38b30 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 ce is used to re
38b40 61 64 20 6f 75 74 20 69 6e 74 65 72 6e 61 6c 0a ad out internal.
38b50 2a 2a 20 73 74 61 74 65 20 6f 66 20 53 51 4c 69 ** state of SQLi
38b60 74 65 20 61 6e 64 20 74 6f 20 69 6e 6a 65 63 74 te and to inject
38b70 20 66 61 75 6c 74 73 20 69 6e 74 6f 20 53 51 4c faults into SQL
38b80 69 74 65 20 66 6f 72 20 74 65 73 74 69 6e 67 0a ite for testing.
38b90 2a 2a 20 70 75 72 70 6f 73 65 73 2e 20 20 54 68 ** purposes. Th
38ba0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
38bb0 72 20 69 73 20 61 6e 20 6f 70 65 72 61 74 69 6f r is an operatio
38bc0 6e 20 63 6f 64 65 20 74 68 61 74 20 64 65 74 65 n code that dete
38bd0 72 6d 69 6e 65 73 0a 2a 2a 20 74 68 65 20 6e 75 rmines.** the nu
38be0 6d 62 65 72 2c 20 6d 65 61 6e 69 6e 67 2c 20 61 mber, meaning, a
38bf0 6e 64 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 nd operation of
38c00 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 70 all subsequent p
38c10 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a arameters..**.**
38c20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 This interface
38c30 69 73 20 6e 6f 74 20 66 6f 72 20 75 73 65 20 62 is not for use b
38c40 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 2e 20 y applications.
38c50 20 49 74 20 65 78 69 73 74 73 20 73 6f 6c 65 6c It exists solel
38c60 79 0a 2a 2a 20 66 6f 72 20 76 65 72 69 66 79 69 y.** for verifyi
38c70 6e 67 20 74 68 65 20 63 6f 72 72 65 63 74 20 6f ng the correct o
38c80 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 peration of the
38c90 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 SQLite library.
38ca0 20 44 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e Depending.** on
38cb0 20 68 6f 77 20 74 68 65 20 53 51 4c 69 74 65 20 how the SQLite
38cc0 6c 69 62 72 61 72 79 20 69 73 20 63 6f 6d 70 69 library is compi
38cd0 6c 65 64 2c 20 74 68 69 73 20 69 6e 74 65 72 66 led, this interf
38ce0 61 63 65 20 6d 69 67 68 74 20 6e 6f 74 20 65 78 ace might not ex
38cf0 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 ist..**.** The d
38d00 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 6f 70 etails of the op
38d10 65 72 61 74 69 6f 6e 20 63 6f 64 65 73 2c 20 74 eration codes, t
38d20 68 65 69 72 20 6d 65 61 6e 69 6e 67 73 2c 20 74 heir meanings, t
38d30 68 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a he parameters.**
38d40 20 74 68 65 79 20 74 61 6b 65 2c 20 61 6e 64 20 they take, and
38d50 77 68 61 74 20 74 68 65 79 20 64 6f 20 61 72 65 what they do are
38d60 20 61 6c 6c 20 73 75 62 6a 65 63 74 20 74 6f 20 all subject to
38d70 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e change without n
38d80 6f 74 69 63 65 2e 0a 2a 2a 20 55 6e 6c 69 6b 65 otice..** Unlike
38d90 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 53 51 4c most of the SQL
38da0 69 74 65 20 41 50 49 2c 20 74 68 69 73 20 66 75 ite API, this fu
38db0 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 75 nction is not gu
38dc0 61 72 61 6e 74 65 65 64 20 74 6f 0a 2a 2a 20 6f aranteed to.** o
38dd0 70 65 72 61 74 65 20 63 6f 6e 73 69 73 74 65 6e perate consisten
38de0 74 6c 79 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c tly from one rel
38df0 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 ease to the next
38e00 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
38e10 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 65 73 74 int sqlite3_test
38e20 5f 63 6f 6e 74 72 6f 6c 28 69 6e 74 20 6f 70 2c _control(int op,
38e30 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ...);../*.** CA
38e40 50 49 33 52 45 46 3a 20 54 65 73 74 69 6e 67 20 PI3REF: Testing
38e50 49 6e 74 65 72 66 61 63 65 20 4f 70 65 72 61 74 Interface Operat
38e60 69 6f 6e 20 43 6f 64 65 73 20 7b 48 31 31 34 31 ion Codes {H1141
38e70 30 7d 20 3c 48 31 31 34 30 30 3e 0a 2a 2a 0a 2a 0} <H11400>.**.*
38e80 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 * These constant
38e90 73 20 61 72 65 20 74 68 65 20 76 61 6c 69 64 20 s are the valid
38ea0 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 65 20 70 operation code p
38eb0 61 72 61 6d 65 74 65 72 73 20 75 73 65 64 0a 2a arameters used.*
38ec0 2a 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 * as the first a
38ed0 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 rgument to [sqli
38ee0 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c te3_test_control
38ef0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ()]..**.** These
38f00 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 parameters and
38f10 74 68 65 69 72 20 6d 65 61 6e 69 6e 67 73 20 61 their meanings a
38f20 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 re subject to ch
38f30 61 6e 67 65 0a 2a 2a 20 77 69 74 68 6f 75 74 20 ange.** without
38f40 6e 6f 74 69 63 65 2e 20 20 54 68 65 73 65 20 76 notice. These v
38f50 61 6c 75 65 73 20 61 72 65 20 66 6f 72 20 74 65 alues are for te
38f60 73 74 69 6e 67 20 70 75 72 70 6f 73 65 73 20 6f sting purposes o
38f70 6e 6c 79 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 nly..** Applicat
38f80 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 ions should not
38f90 75 73 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 use any of these
38fa0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 74 parameters or t
38fb0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 he.** [sqlite3_t
38fc0 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 est_control()] i
38fd0 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 nterface..*/.#de
38fe0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 fine SQLITE_TEST
38ff0 43 54 52 4c 5f 50 52 4e 47 5f 53 41 56 45 20 20 CTRL_PRNG_SAVE
39000 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 5.
39010 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
39020 45 53 54 43 54 52 4c 5f 50 52 4e 47 5f 52 45 53 ESTCTRL_PRNG_RES
39030 54 4f 52 45 20 20 20 20 20 20 20 20 20 20 20 20 TORE
39040 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 6.#define SQLIT
39050 45 5f 54 45 53 54 43 54 52 4c 5f 50 52 4e 47 5f E_TESTCTRL_PRNG_
39060 52 45 53 45 54 20 20 20 20 20 20 20 20 20 20 20 RESET
39070 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 7.#define SQ
39080 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 42 49 LITE_TESTCTRL_BI
39090 54 56 45 43 5f 54 45 53 54 20 20 20 20 20 20 20 TVEC_TEST
390a0 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 8.#define
390b0 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c SQLITE_TESTCTRL
390c0 5f 46 41 55 4c 54 5f 49 4e 53 54 41 4c 4c 20 20 _FAULT_INSTALL
390d0 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 9.#def
390e0 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 ine SQLITE_TESTC
390f0 54 52 4c 5f 42 45 4e 49 47 4e 5f 4d 41 4c 4c 4f TRL_BENIGN_MALLO
39100 43 5f 48 4f 4f 4b 53 20 20 20 20 20 31 30 0a 23 C_HOOKS 10.#
39110 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 define SQLITE_TE
39120 53 54 43 54 52 4c 5f 50 45 4e 44 49 4e 47 5f 42 STCTRL_PENDING_B
39130 59 54 45 20 20 20 20 20 20 20 20 20 20 20 20 31 YTE 1
39140 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
39150 5f 54 45 53 54 43 54 52 4c 5f 41 53 53 45 52 54 _TESTCTRL_ASSERT
39160 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
39170 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 12.#define SQL
39180 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 41 4c 57 ITE_TESTCTRL_ALW
39190 41 59 53 20 20 20 20 20 20 20 20 20 20 20 20 20 AYS
391a0 20 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 13.#define
391b0 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f SQLITE_TESTCTRL_
391c0 52 45 53 45 52 56 45 20 20 20 20 20 20 20 20 20 RESERVE
391d0 20 20 20 20 20 20 20 20 31 34 0a 0a 2f 2a 0a 2a 14../*.*
391e0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 69 * CAPI3REF: SQLi
391f0 74 65 20 52 75 6e 74 69 6d 65 20 53 74 61 74 75 te Runtime Statu
39200 73 20 7b 48 31 37 32 30 30 7d 20 3c 53 36 30 32 s {H17200} <S602
39210 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 00>.** EXPERIMEN
39220 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 TAL.**.** This i
39230 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 nterface is used
39240 20 74 6f 20 72 65 74 72 69 65 76 65 20 72 75 6e to retrieve run
39250 74 69 6d 65 20 73 74 61 74 75 73 20 69 6e 66 6f time status info
39260 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 rmation.** about
39270 20 74 68 65 20 70 72 65 66 6f 72 6d 61 6e 63 65 the preformance
39280 20 6f 66 20 53 51 4c 69 74 65 2c 20 61 6e 64 20 of SQLite, and
39290 6f 70 74 69 6f 6e 61 6c 6c 79 20 74 6f 20 72 65 optionally to re
392a0 73 65 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 68 set various.** h
392b0 69 67 68 77 61 74 65 72 20 6d 61 72 6b 73 2e 20 ighwater marks.
392c0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
392d0 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 ent is an intege
392e0 72 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 r code for.** th
392f0 65 20 73 70 65 63 69 66 69 63 20 70 61 72 61 6d e specific param
39300 65 74 65 72 20 74 6f 20 6d 65 61 73 75 72 65 2e eter to measure.
39310 20 20 52 65 63 6f 67 6e 69 7a 65 64 20 69 6e 74 Recognized int
39320 65 67 65 72 20 63 6f 64 65 73 0a 2a 2a 20 61 72 eger codes.** ar
39330 65 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 5b 53 e of the form [S
39340 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 45 4d QLITE_STATUS_MEM
39350 4f 52 59 5f 55 53 45 44 20 7c 20 53 51 4c 49 54 ORY_USED | SQLIT
39360 45 5f 53 54 41 54 55 53 5f 2e 2e 2e 5d 2e 0a 2a E_STATUS_...]..*
39370 2a 20 54 68 65 20 63 75 72 72 65 6e 74 20 76 61 * The current va
39380 6c 75 65 20 6f 66 20 74 68 65 20 70 61 72 61 6d lue of the param
39390 65 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 eter is returned
393a0 20 69 6e 74 6f 20 2a 70 43 75 72 72 65 6e 74 2e into *pCurrent.
393b0 0a 2a 2a 20 54 68 65 20 68 69 67 68 65 73 74 20 .** The highest
393c0 72 65 63 6f 72 64 65 64 20 76 61 6c 75 65 20 69 recorded value i
393d0 73 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 s returned in *p
393e0 48 69 67 68 77 61 74 65 72 2e 20 20 49 66 20 74 Highwater. If t
393f0 68 65 0a 2a 2a 20 72 65 73 65 74 46 6c 61 67 20 he.** resetFlag
39400 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 is true, then th
39410 65 20 68 69 67 68 65 73 74 20 72 65 63 6f 72 64 e highest record
39420 20 76 61 6c 75 65 20 69 73 20 72 65 73 65 74 20 value is reset
39430 61 66 74 65 72 0a 2a 2a 20 2a 70 48 69 67 68 77 after.** *pHighw
39440 61 74 65 72 20 69 73 20 77 72 69 74 74 65 6e 2e ater is written.
39450 20 53 6f 6d 65 20 70 61 72 61 6d 65 74 65 72 73 Some parameters
39460 20 64 6f 20 6e 6f 74 20 72 65 63 6f 72 64 20 74 do not record t
39470 68 65 20 68 69 67 68 65 73 74 0a 2a 2a 20 76 61 he highest.** va
39480 6c 75 65 2e 20 20 46 6f 72 20 74 68 6f 73 65 20 lue. For those
39490 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6e 6f parameters.** no
394a0 74 68 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e thing is written
394b0 20 69 6e 74 6f 20 2a 70 48 69 67 68 77 61 74 65 into *pHighwate
394c0 72 20 61 6e 64 20 74 68 65 20 72 65 73 65 74 46 r and the resetF
394d0 6c 61 67 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a lag is ignored..
394e0 2a 2a 20 4f 74 68 65 72 20 70 61 72 61 6d 65 74 ** Other paramet
394f0 65 72 73 20 72 65 63 6f 72 64 20 6f 6e 6c 79 20 ers record only
39500 74 68 65 20 68 69 67 68 77 61 74 65 72 20 6d 61 the highwater ma
39510 72 6b 20 61 6e 64 20 6e 6f 74 20 74 68 65 20 63 rk and not the c
39520 75 72 72 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 2e urrent.** value.
39530 20 20 46 6f 72 20 74 68 65 73 65 20 6c 61 74 74 For these latt
39540 65 72 20 70 61 72 61 6d 65 74 65 72 73 20 6e 6f er parameters no
39550 74 68 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e thing is written
39560 20 69 6e 74 6f 20 2a 70 43 75 72 72 65 6e 74 2e into *pCurrent.
39570 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
39580 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49 ine returns SQLI
39590 54 45 5f 4f 4b 20 6f 6e 20 73 75 63 63 65 73 73 TE_OK on success
395a0 20 61 6e 64 20 61 20 6e 6f 6e 2d 7a 65 72 6f 0a and a non-zero.
395b0 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 ** [error code]
395c0 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a on failure..**.*
395d0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 * This routine i
395e0 73 20 74 68 72 65 61 64 73 61 66 65 20 62 75 74 s threadsafe but
395f0 20 69 73 20 6e 6f 74 20 61 74 6f 6d 69 63 2e 20 is not atomic.
39600 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 This routine ca
39610 6e 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 77 n be.** called w
39620 68 69 6c 65 20 6f 74 68 65 72 20 74 68 72 65 61 hile other threa
39630 64 73 20 61 72 65 20 72 75 6e 6e 69 6e 67 20 74 ds are running t
39640 68 65 20 73 61 6d 65 20 6f 72 20 64 69 66 66 65 he same or diffe
39650 72 65 6e 74 20 53 51 4c 69 74 65 0a 2a 2a 20 69 rent SQLite.** i
39660 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 nterfaces. Howe
39670 76 65 72 20 74 68 65 20 76 61 6c 75 65 73 20 72 ver the values r
39680 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 43 75 72 eturned in *pCur
39690 72 65 6e 74 20 61 6e 64 0a 2a 2a 20 2a 70 48 69 rent and.** *pHi
396a0 67 68 77 61 74 65 72 20 72 65 66 6c 65 63 74 20 ghwater reflect
396b0 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 53 51 the status of SQ
396c0 4c 69 74 65 20 61 74 20 64 69 66 66 65 72 65 6e Lite at differen
396d0 74 20 70 6f 69 6e 74 73 20 69 6e 20 74 69 6d 65 t points in time
396e0 0a 2a 2a 20 61 6e 64 20 69 74 20 69 73 20 70 6f .** and it is po
396f0 73 73 69 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 ssible that anot
39700 68 65 72 20 74 68 72 65 61 64 20 6d 69 67 68 74 her thread might
39710 20 63 68 61 6e 67 65 20 74 68 65 20 70 61 72 61 change the para
39720 6d 65 74 65 72 0a 2a 2a 20 69 6e 20 62 65 74 77 meter.** in betw
39730 65 65 6e 20 74 68 65 20 74 69 6d 65 73 20 77 68 een the times wh
39740 65 6e 20 2a 70 43 75 72 72 65 6e 74 20 61 6e 64 en *pCurrent and
39750 20 2a 70 48 69 67 68 77 61 74 65 72 20 61 72 65 *pHighwater are
39760 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 written..**.**
39770 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 See also: [sqlit
39780 65 33 5f 64 62 5f 73 74 61 74 75 73 28 29 5d 0a e3_db_status()].
39790 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 */.SQLITE_API SQ
397a0 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 LITE_EXPERIMENTA
397b0 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 L int sqlite3_st
397c0 61 74 75 73 28 69 6e 74 20 6f 70 2c 20 69 6e 74 atus(int op, int
397d0 20 2a 70 43 75 72 72 65 6e 74 2c 20 69 6e 74 20 *pCurrent, int
397e0 2a 70 48 69 67 68 77 61 74 65 72 2c 20 69 6e 74 *pHighwater, int
397f0 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 0a 2f resetFlag);.../
39800 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
39810 74 61 74 75 73 20 50 61 72 61 6d 65 74 65 72 73 tatus Parameters
39820 20 7b 48 31 37 32 35 30 7d 20 3c 48 31 37 32 30 {H17250} <H1720
39830 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 0>.** EXPERIMENT
39840 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 AL.**.** These i
39850 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 nteger constants
39860 20 64 65 73 69 67 6e 61 74 65 20 76 61 72 69 6f designate vario
39870 75 73 20 72 75 6e 2d 74 69 6d 65 20 73 74 61 74 us run-time stat
39880 75 73 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a us parameters.**
39890 20 74 68 61 74 20 63 61 6e 20 62 65 20 72 65 74 that can be ret
398a0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 urned by [sqlite
398b0 33 5f 73 74 61 74 75 73 28 29 5d 2e 0a 2a 2a 0a 3_status()]..**.
398c0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 ** <dl>.** <dt>S
398d0 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 45 4d QLITE_STATUS_MEM
398e0 4f 52 59 5f 55 53 45 44 3c 2f 64 74 3e 0a 2a 2a ORY_USED</dt>.**
398f0 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 <dd>This parame
39900 74 65 72 20 69 73 20 74 68 65 20 63 75 72 72 65 ter is the curre
39910 6e 74 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d nt amount of mem
39920 6f 72 79 20 63 68 65 63 6b 65 64 20 6f 75 74 0a ory checked out.
39930 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ** using [sqlite
39940 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 65 69 74 3_malloc()], eit
39950 68 65 72 20 64 69 72 65 63 74 6c 79 20 6f 72 20 her directly or
39960 69 6e 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 indirectly. The
39970 0a 2a 2a 20 66 69 67 75 72 65 20 69 6e 63 6c 75 .** figure inclu
39980 64 65 73 20 63 61 6c 6c 73 20 6d 61 64 65 20 74 des calls made t
39990 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f o [sqlite3_mallo
399a0 63 28 29 5d 20 62 79 20 74 68 65 20 61 70 70 6c c()] by the appl
399b0 69 63 61 74 69 6f 6e 0a 2a 2a 20 61 6e 64 20 69 ication.** and i
399c0 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 75 nternal memory u
399d0 73 61 67 65 20 62 79 20 74 68 65 20 53 51 4c 69 sage by the SQLi
399e0 74 65 20 6c 69 62 72 61 72 79 2e 20 20 53 63 72 te library. Scr
399f0 61 74 63 68 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 atch memory.** c
39a00 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 5b 53 51 ontrolled by [SQ
39a10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 LITE_CONFIG_SCRA
39a20 54 43 48 5d 20 61 6e 64 20 61 75 78 69 6c 69 61 TCH] and auxilia
39a30 72 79 20 70 61 67 65 2d 63 61 63 68 65 0a 2a 2a ry page-cache.**
39a40 20 6d 65 6d 6f 72 79 20 63 6f 6e 74 72 6f 6c 6c memory controll
39a50 65 64 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f ed by [SQLITE_CO
39a60 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 20 NFIG_PAGECACHE]
39a70 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 is not included
39a80 69 6e 0a 2a 2a 20 74 68 69 73 20 70 61 72 61 6d in.** this param
39a90 65 74 65 72 2e 20 20 54 68 65 20 61 6d 6f 75 6e eter. The amoun
39aa0 74 20 72 65 74 75 72 6e 65 64 20 69 73 20 74 68 t returned is th
39ab0 65 20 73 75 6d 20 6f 66 20 74 68 65 20 61 6c 6c e sum of the all
39ac0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 73 69 7a 65 73 ocation.** sizes
39ad0 20 61 73 20 72 65 70 6f 72 74 65 64 20 62 79 20 as reported by
39ae0 74 68 65 20 78 53 69 7a 65 20 6d 65 74 68 6f 64 the xSize method
39af0 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d in [sqlite3_mem
39b00 5f 6d 65 74 68 6f 64 73 5d 2e 3c 2f 64 64 3e 0a _methods].</dd>.
39b10 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
39b20 5f 53 54 41 54 55 53 5f 4d 41 4c 4c 4f 43 5f 53 _STATUS_MALLOC_S
39b30 49 5a 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e IZE</dt>.** <dd>
39b40 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 This parameter r
39b50 65 63 6f 72 64 73 20 74 68 65 20 6c 61 72 67 65 ecords the large
39b60 73 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 st memory alloca
39b70 74 69 6f 6e 20 72 65 71 75 65 73 74 0a 2a 2a 20 tion request.**
39b80 68 61 6e 64 65 64 20 74 6f 20 5b 73 71 6c 69 74 handed to [sqlit
39b90 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 e3_malloc()] or
39ba0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 [sqlite3_realloc
39bb0 28 29 5d 20 28 6f 72 20 74 68 65 69 72 0a 2a 2a ()] (or their.**
39bc0 20 69 6e 74 65 72 6e 61 6c 20 65 71 75 69 76 61 internal equiva
39bd0 6c 65 6e 74 73 29 2e 20 20 4f 6e 6c 79 20 74 68 lents). Only th
39be0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
39bf0 20 69 6e 20 74 68 65 0a 2a 2a 20 2a 70 48 69 67 in the.** *pHig
39c00 68 77 61 74 65 72 20 70 61 72 61 6d 65 74 65 72 hwater parameter
39c10 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 to [sqlite3_sta
39c20 74 75 73 28 29 5d 20 69 73 20 6f 66 20 69 6e 74 tus()] is of int
39c30 65 72 65 73 74 2e 20 20 0a 2a 2a 20 54 68 65 20 erest. .** The
39c40 76 61 6c 75 65 20 77 72 69 74 74 65 6e 20 69 6e value written in
39c50 74 6f 20 74 68 65 20 2a 70 43 75 72 72 65 6e 74 to the *pCurrent
39c60 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 6e parameter is un
39c70 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a defined.</dd>.**
39c80 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 .** <dt>SQLITE_S
39c90 54 41 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f TATUS_PAGECACHE_
39ca0 55 53 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 USED</dt>.** <dd
39cb0 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 >This parameter
39cc0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
39cd0 65 72 20 6f 66 20 70 61 67 65 73 20 75 73 65 64 er of pages used
39ce0 20 6f 75 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b out of the.** [
39cf0 70 61 67 65 63 61 63 68 65 20 6d 65 6d 6f 72 79 pagecache memory
39d00 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 74 68 61 74 allocator] that
39d10 20 77 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20 was configured
39d20 75 73 69 6e 67 20 0a 2a 2a 20 5b 53 51 4c 49 54 using .** [SQLIT
39d30 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 E_CONFIG_PAGECAC
39d40 48 45 5d 2e 20 20 54 68 65 0a 2a 2a 20 76 61 6c HE]. The.** val
39d50 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 69 ue returned is i
39d60 6e 20 70 61 67 65 73 2c 20 6e 6f 74 20 69 6e 20 n pages, not in
39d70 62 79 74 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a bytes.</dd>.**.*
39d80 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 * <dt>SQLITE_STA
39d90 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f 4f 56 TUS_PAGECACHE_OV
39da0 45 52 46 4c 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c ERFLOW</dt>.** <
39db0 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65 dd>This paramete
39dc0 72 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 r returns the nu
39dd0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 mber of bytes of
39de0 20 70 61 67 65 20 63 61 63 68 65 0a 2a 2a 20 61 page cache.** a
39df0 6c 6c 6f 63 61 74 69 6f 6e 20 77 68 69 63 68 20 llocation which
39e00 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 73 74 61 could not be sta
39e10 74 69 73 66 69 65 64 20 62 79 20 74 68 65 20 5b tisfied by the [
39e20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 SQLITE_CONFIG_PA
39e30 47 45 43 41 43 48 45 5d 0a 2a 2a 20 62 75 66 66 GECACHE].** buff
39e40 65 72 20 61 6e 64 20 77 68 65 72 65 20 66 6f 72 er and where for
39e50 63 65 64 20 74 6f 20 6f 76 65 72 66 6c 6f 77 20 ced to overflow
39e60 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c to [sqlite3_mall
39e70 6f 63 28 29 5d 2e 20 20 54 68 65 0a 2a 2a 20 72 oc()]. The.** r
39e80 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 6e eturned value in
39e90 63 6c 75 64 65 73 20 61 6c 6c 6f 63 61 74 69 6f cludes allocatio
39ea0 6e 73 20 74 68 61 74 20 6f 76 65 72 66 6c 6f 77 ns that overflow
39eb0 65 64 20 62 65 63 61 75 73 65 20 74 68 65 79 0a ed because they.
39ec0 2a 2a 20 77 68 65 72 65 20 74 6f 6f 20 6c 61 72 ** where too lar
39ed0 67 65 20 28 74 68 65 79 20 77 65 72 65 20 6c 61 ge (they were la
39ee0 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 22 73 rger than the "s
39ef0 7a 22 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a z" parameter to.
39f00 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ** [SQLITE_CONFI
39f10 47 5f 50 41 47 45 43 41 43 48 45 5d 29 20 61 6e G_PAGECACHE]) an
39f20 64 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 74 68 d allocations th
39f30 61 74 20 6f 76 65 72 66 6c 6f 77 65 64 20 62 65 at overflowed be
39f40 63 61 75 73 65 0a 2a 2a 20 6e 6f 20 73 70 61 63 cause.** no spac
39f50 65 20 77 61 73 20 6c 65 66 74 20 69 6e 20 74 68 e was left in th
39f60 65 20 70 61 67 65 20 63 61 63 68 65 2e 3c 2f 64 e page cache.</d
39f70 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
39f80 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45 43 ITE_STATUS_PAGEC
39f90 41 43 48 45 5f 53 49 5a 45 3c 2f 64 74 3e 0a 2a ACHE_SIZE</dt>.*
39fa0 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d * <dd>This param
39fb0 65 74 65 72 20 72 65 63 6f 72 64 73 20 74 68 65 eter records the
39fc0 20 6c 61 72 67 65 73 74 20 6d 65 6d 6f 72 79 20 largest memory
39fd0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 allocation reque
39fe0 73 74 0a 2a 2a 20 68 61 6e 64 65 64 20 74 6f 20 st.** handed to
39ff0 5b 70 61 67 65 63 61 63 68 65 20 6d 65 6d 6f 72 [pagecache memor
3a000 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 2e 20 20 4f y allocator]. O
3a010 6e 6c 79 20 74 68 65 20 76 61 6c 75 65 20 72 65 nly the value re
3a020 74 75 72 6e 65 64 20 69 6e 20 74 68 65 0a 2a 2a turned in the.**
3a030 20 2a 70 48 69 67 68 77 61 74 65 72 20 70 61 72 *pHighwater par
3a040 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 ameter to [sqlit
3a050 65 33 5f 73 74 61 74 75 73 28 29 5d 20 69 73 20 e3_status()] is
3a060 6f 66 20 69 6e 74 65 72 65 73 74 2e 20 20 0a 2a of interest. .*
3a070 2a 20 54 68 65 20 76 61 6c 75 65 20 77 72 69 74 * The value writ
3a080 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 2a 70 43 ten into the *pC
3a090 75 72 72 65 6e 74 20 70 61 72 61 6d 65 74 65 72 urrent parameter
3a0a0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f is undefined.</
3a0b0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
3a0c0 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41 LITE_STATUS_SCRA
3a0d0 54 43 48 5f 55 53 45 44 3c 2f 64 74 3e 0a 2a 2a TCH_USED</dt>.**
3a0e0 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 <dd>This parame
3a0f0 74 65 72 20 72 65 74 75 72 6e 73 20 74 68 65 20 ter returns the
3a100 6e 75 6d 62 65 72 20 6f 66 20 61 6c 6c 6f 63 61 number of alloca
3a110 74 69 6f 6e 73 20 75 73 65 64 20 6f 75 74 20 6f tions used out o
3a120 66 20 74 68 65 0a 2a 2a 20 5b 73 63 72 61 74 63 f the.** [scratc
3a130 68 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 h memory allocat
3a140 6f 72 5d 20 63 6f 6e 66 69 67 75 72 65 64 20 75 or] configured u
3a150 73 69 6e 67 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f sing.** [SQLITE_
3a160 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 2e CONFIG_SCRATCH].
3a170 20 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 The value retu
3a180 72 6e 65 64 20 69 73 20 69 6e 20 61 6c 6c 6f 63 rned is in alloc
3a190 61 74 69 6f 6e 73 2c 20 6e 6f 74 0a 2a 2a 20 69 ations, not.** i
3a1a0 6e 20 62 79 74 65 73 2e 20 20 53 69 6e 63 65 20 n bytes. Since
3a1b0 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 20 a single thread
3a1c0 6d 61 79 20 6f 6e 6c 79 20 68 61 76 65 20 6f 6e may only have on
3a1d0 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 e scratch alloca
3a1e0 74 69 6f 6e 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 tion.** outstand
3a1f0 69 6e 67 20 61 74 20 74 69 6d 65 2c 20 74 68 69 ing at time, thi
3a200 73 20 70 61 72 61 6d 65 74 65 72 20 61 6c 73 6f s parameter also
3a210 20 72 65 70 6f 72 74 73 20 74 68 65 20 6e 75 6d reports the num
3a220 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 0a 2a ber of threads.*
3a230 2a 20 75 73 69 6e 67 20 73 63 72 61 74 63 68 20 * using scratch
3a240 6d 65 6d 6f 72 79 20 61 74 20 74 68 65 20 73 61 memory at the sa
3a250 6d 65 20 74 69 6d 65 2e 3c 2f 64 64 3e 0a 2a 2a me time.</dd>.**
3a260 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 .** <dt>SQLITE_S
3a270 54 41 54 55 53 5f 53 43 52 41 54 43 48 5f 4f 56 TATUS_SCRATCH_OV
3a280 45 52 46 4c 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c ERFLOW</dt>.** <
3a290 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65 dd>This paramete
3a2a0 72 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 r returns the nu
3a2b0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 mber of bytes of
3a2c0 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 0a scratch memory.
3a2d0 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 77 68 ** allocation wh
3a2e0 69 63 68 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 ich could not be
3a2f0 20 73 74 61 74 69 73 66 69 65 64 20 62 79 20 74 statisfied by t
3a300 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 he [SQLITE_CONFI
3a310 47 5f 53 43 52 41 54 43 48 5d 0a 2a 2a 20 62 75 G_SCRATCH].** bu
3a320 66 66 65 72 20 61 6e 64 20 77 68 65 72 65 20 66 ffer and where f
3a330 6f 72 63 65 64 20 74 6f 20 6f 76 65 72 66 6c 6f orced to overflo
3a340 77 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 w to [sqlite3_ma
3a350 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 76 61 lloc()]. The va
3a360 6c 75 65 73 0a 2a 2a 20 72 65 74 75 72 6e 65 64 lues.** returned
3a370 20 69 6e 63 6c 75 64 65 20 6f 76 65 72 66 6c 6f include overflo
3a380 77 73 20 62 65 63 61 75 73 65 20 74 68 65 20 72 ws because the r
3a390 65 71 75 65 73 74 65 64 20 61 6c 6c 6f 63 61 74 equested allocat
3a3a0 69 6f 6e 20 77 61 73 20 74 6f 6f 0a 2a 2a 20 6c ion was too.** l
3a3b0 61 72 67 65 72 20 28 74 68 61 74 20 69 73 2c 20 arger (that is,
3a3c0 62 65 63 61 75 73 65 20 74 68 65 20 72 65 71 75 because the requ
3a3d0 65 73 74 65 64 20 61 6c 6c 6f 63 61 74 69 6f 6e ested allocation
3a3e0 20 77 61 73 20 6c 61 72 67 65 72 20 74 68 61 6e was larger than
3a3f0 20 74 68 65 0a 2a 2a 20 22 73 7a 22 20 70 61 72 the.** "sz" par
3a400 61 6d 65 74 65 72 20 74 6f 20 5b 53 51 4c 49 54 ameter to [SQLIT
3a410 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 E_CONFIG_SCRATCH
3a420 5d 29 20 61 6e 64 20 62 65 63 61 75 73 65 20 6e ]) and because n
3a430 6f 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 o scratch buffer
3a440 0a 2a 2a 20 73 6c 6f 74 73 20 77 65 72 65 20 61 .** slots were a
3a450 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 3c 2f 64 vailable..** </d
3a460 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
3a470 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54 ITE_STATUS_SCRAT
3a480 43 48 5f 53 49 5a 45 3c 2f 64 74 3e 0a 2a 2a 20 CH_SIZE</dt>.**
3a490 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 <dd>This paramet
3a4a0 65 72 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c er records the l
3a4b0 61 72 67 65 73 74 20 6d 65 6d 6f 72 79 20 61 6c argest memory al
3a4c0 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 location request
3a4d0 0a 2a 2a 20 68 61 6e 64 65 64 20 74 6f 20 5b 73 .** handed to [s
3a4e0 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 61 6c cratch memory al
3a4f0 6c 6f 63 61 74 6f 72 5d 2e 20 20 4f 6e 6c 79 20 locator]. Only
3a500 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
3a510 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 2a 70 48 ed in the.** *pH
3a520 69 67 68 77 61 74 65 72 20 70 61 72 61 6d 65 74 ighwater paramet
3a530 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 er to [sqlite3_s
3a540 74 61 74 75 73 28 29 5d 20 69 73 20 6f 66 20 69 tatus()] is of i
3a550 6e 74 65 72 65 73 74 2e 20 20 0a 2a 2a 20 54 68 nterest. .** Th
3a560 65 20 76 61 6c 75 65 20 77 72 69 74 74 65 6e 20 e value written
3a570 69 6e 74 6f 20 74 68 65 20 2a 70 43 75 72 72 65 into the *pCurre
3a580 6e 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nt parameter is
3a590 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a undefined.</dd>.
3a5a0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
3a5b0 5f 53 54 41 54 55 53 5f 50 41 52 53 45 52 5f 53 _STATUS_PARSER_S
3a5c0 54 41 43 4b 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 TACK</dt>.** <dd
3a5d0 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 >This parameter
3a5e0 72 65 63 6f 72 64 73 20 74 68 65 20 64 65 65 70 records the deep
3a5f0 65 73 74 20 70 61 72 73 65 72 20 73 74 61 63 6b est parser stack
3a600 2e 20 20 49 74 20 69 73 20 6f 6e 6c 79 0a 2a 2a . It is only.**
3a610 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 53 meaningful if S
3a620 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
3a630 64 20 77 69 74 68 20 5b 59 59 54 52 41 43 4b 4d d with [YYTRACKM
3a640 41 58 53 54 41 43 4b 44 45 50 54 48 5d 2e 3c 2f AXSTACKDEPTH].</
3a650 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a dd>.** </dl>.**.
3a660 2a 2a 20 4e 65 77 20 73 74 61 74 75 73 20 70 61 ** New status pa
3a670 72 61 6d 65 74 65 72 73 20 6d 61 79 20 62 65 20 rameters may be
3a680 61 64 64 65 64 20 66 72 6f 6d 20 74 69 6d 65 20 added from time
3a690 74 6f 20 74 69 6d 65 2e 0a 2a 2f 0a 23 64 65 66 to time..*/.#def
3a6a0 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 ine SQLITE_STATU
3a6b0 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 20 20 20 S_MEMORY_USED
3a6c0 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 0.#define
3a6d0 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 SQLITE_STATUS_P
3a6e0 41 47 45 43 41 43 48 45 5f 55 53 45 44 20 20 20 AGECACHE_USED
3a6f0 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 1.#define SQ
3a700 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45 LITE_STATUS_PAGE
3a710 43 41 43 48 45 5f 4f 56 45 52 46 4c 4f 57 20 20 CACHE_OVERFLOW
3a720 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 2.#define SQLIT
3a730 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54 43 48 E_STATUS_SCRATCH
3a740 5f 55 53 45 44 20 20 20 20 20 20 20 20 20 33 0a _USED 3.
3a750 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
3a760 54 41 54 55 53 5f 53 43 52 41 54 43 48 5f 4f 56 TATUS_SCRATCH_OV
3a770 45 52 46 4c 4f 57 20 20 20 20 20 34 0a 23 64 65 ERFLOW 4.#de
3a780 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 fine SQLITE_STAT
3a790 55 53 5f 4d 41 4c 4c 4f 43 5f 53 49 5a 45 20 20 US_MALLOC_SIZE
3a7a0 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 5.#defin
3a7b0 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f e SQLITE_STATUS_
3a7c0 50 41 52 53 45 52 5f 53 54 41 43 4b 20 20 20 20 PARSER_STACK
3a7d0 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 6.#define S
3a7e0 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 QLITE_STATUS_PAG
3a7f0 45 43 41 43 48 45 5f 53 49 5a 45 20 20 20 20 20 ECACHE_SIZE
3a800 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 7.#define SQLI
3a810 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54 43 TE_STATUS_SCRATC
3a820 48 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 38 H_SIZE 8
3a830 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
3a840 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 : Database Conne
3a850 63 74 69 6f 6e 20 53 74 61 74 75 73 20 7b 48 31 ction Status {H1
3a860 37 35 30 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 7500} <S60200>.*
3a870 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a * EXPERIMENTAL.*
3a880 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 *.** This interf
3a890 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 ace is used to r
3a8a0 65 74 72 69 65 76 65 20 72 75 6e 74 69 6d 65 20 etrieve runtime
3a8b0 73 74 61 74 75 73 20 69 6e 66 6f 72 6d 61 74 69 status informati
3a8c0 6f 6e 20 0a 2a 2a 20 61 62 6f 75 74 20 61 20 73 on .** about a s
3a8d0 69 6e 67 6c 65 20 5b 64 61 74 61 62 61 73 65 20 ingle [database
3a8e0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 connection]. Th
3a8f0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
3a900 20 69 73 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 is the.** datab
3a910 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f ase connection o
3a920 62 6a 65 63 74 20 74 6f 20 62 65 20 69 6e 74 65 bject to be inte
3a930 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20 73 rrogated. The s
3a940 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 0a 2a econd argument.*
3a950 2a 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 * is the paramet
3a960 65 72 20 74 6f 20 69 6e 74 65 72 72 6f 67 61 74 er to interrogat
3a970 65 2e 20 20 43 75 72 72 65 6e 74 6c 79 2c 20 74 e. Currently, t
3a980 68 65 20 6f 6e 6c 79 20 61 6c 6c 6f 77 65 64 20 he only allowed
3a990 76 61 6c 75 65 0a 2a 2a 20 66 6f 72 20 74 68 65 value.** for the
3a9a0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
3a9b0 72 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 42 53 r is [SQLITE_DBS
3a9c0 54 41 54 55 53 5f 4c 4f 4f 4b 41 53 49 44 45 5f TATUS_LOOKASIDE_
3a9d0 55 53 45 44 5d 2e 0a 2a 2a 20 41 64 64 69 74 69 USED]..** Additi
3a9e0 6f 6e 61 6c 20 6f 70 74 69 6f 6e 73 20 77 69 6c onal options wil
3a9f0 6c 20 6c 69 6b 65 6c 79 20 61 70 70 65 61 72 20 l likely appear
3aa00 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
3aa10 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a es of SQLite..**
3aa20 0a 2a 2a 20 54 68 65 20 63 75 72 72 65 6e 74 20 .** The current
3aa30 76 61 6c 75 65 20 6f 66 20 74 68 65 20 72 65 71 value of the req
3aa40 75 65 73 74 65 64 20 70 61 72 61 6d 65 74 65 72 uested parameter
3aa50 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f is written into
3aa60 20 2a 70 43 75 72 0a 2a 2a 20 61 6e 64 20 74 68 *pCur.** and th
3aa70 65 20 68 69 67 68 65 73 74 20 69 6e 73 74 61 6e e highest instan
3aa80 74 61 6e 65 6f 75 73 20 76 61 6c 75 65 20 69 73 taneous value is
3aa90 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 written into *p
3aaa0 48 69 77 74 72 2e 20 20 49 66 0a 2a 2a 20 74 68 Hiwtr. If.** th
3aab0 65 20 72 65 73 65 74 46 6c 67 20 69 73 20 74 72 e resetFlg is tr
3aac0 75 65 2c 20 74 68 65 6e 20 74 68 65 20 68 69 67 ue, then the hig
3aad0 68 65 73 74 20 69 6e 73 74 61 6e 74 61 6e 65 6f hest instantaneo
3aae0 75 73 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 72 us value is.** r
3aaf0 65 73 65 74 20 62 61 63 6b 20 64 6f 77 6e 20 74 eset back down t
3ab00 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 o the current va
3ab10 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 lue..**.** See a
3ab20 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 73 74 lso: [sqlite3_st
3ab30 61 74 75 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c atus()] and [sql
3ab40 69 74 65 33 5f 73 74 6d 74 5f 73 74 61 74 75 73 ite3_stmt_status
3ab50 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ()]..*/.SQLITE_A
3ab60 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 PI SQLITE_EXPERI
3ab70 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 MENTAL int sqlit
3ab80 65 33 5f 64 62 5f 73 74 61 74 75 73 28 73 71 6c e3_db_status(sql
3ab90 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 69 ite3*, int op, i
3aba0 6e 74 20 2a 70 43 75 72 2c 20 69 6e 74 20 2a 70 nt *pCur, int *p
3abb0 48 69 77 74 72 2c 20 69 6e 74 20 72 65 73 65 74 Hiwtr, int reset
3abc0 46 6c 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 Flg);../*.** CAP
3abd0 49 33 52 45 46 3a 20 53 74 61 74 75 73 20 50 61 I3REF: Status Pa
3abe0 72 61 6d 65 74 65 72 73 20 66 6f 72 20 64 61 74 rameters for dat
3abf0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
3ac00 73 20 7b 48 31 37 35 32 30 7d 20 3c 48 31 37 35 s {H17520} <H175
3ac10 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 00>.** EXPERIMEN
3ac20 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 TAL.**.** These
3ac30 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 constants are th
3ac40 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 e available inte
3ac50 67 65 72 20 22 76 65 72 62 73 22 20 74 68 61 74 ger "verbs" that
3ac60 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 can be passed a
3ac70 73 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 s.** the second
3ac80 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
3ac90 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 [sqlite3_db_stat
3aca0 75 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e us()] interface.
3acb0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 76 65 72 62 73 .**.** New verbs
3acc0 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e may be added in
3acd0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
3ace0 20 6f 66 20 53 51 4c 69 74 65 2e 20 45 78 69 73 of SQLite. Exis
3acf0 74 69 6e 67 20 76 65 72 62 73 0a 2a 2a 20 6d 69 ting verbs.** mi
3ad00 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e ght be discontin
3ad10 75 65 64 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e ued. Application
3ad20 73 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 s should check t
3ad30 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 he return code f
3ad40 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f rom.** [sqlite3_
3ad50 64 62 5f 73 74 61 74 75 73 28 29 5d 20 74 6f 20 db_status()] to
3ad60 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 make sure that t
3ad70 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 0a he call worked..
3ad80 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f ** The [sqlite3_
3ad90 64 62 5f 73 74 61 74 75 73 28 29 5d 20 69 6e 74 db_status()] int
3ada0 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 erface will retu
3adb0 72 6e 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 65 72 rn a non-zero er
3adc0 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 69 66 20 61 ror code.** if a
3add0 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 discontinued or
3ade0 20 75 6e 73 75 70 70 6f 72 74 65 64 20 76 65 72 unsupported ver
3adf0 62 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a b is invoked..**
3ae00 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e .** <dl>.** <dt>
3ae10 53 51 4c 49 54 45 5f 44 42 53 54 41 54 55 53 5f SQLITE_DBSTATUS_
3ae20 4c 4f 4f 4b 41 53 49 44 45 5f 55 53 45 44 3c 2f LOOKASIDE_USED</
3ae30 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 dt>.** <dd>This
3ae40 70 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 6e parameter return
3ae50 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
3ae60 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 lookaside memory
3ae70 20 73 6c 6f 74 73 20 63 75 72 72 65 6e 74 6c 79 slots currently
3ae80 0a 2a 2a 20 63 68 65 63 6b 65 64 20 6f 75 74 2e .** checked out.
3ae90 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a </dd>.** </dl>.*
3aea0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
3aeb0 5f 44 42 53 54 41 54 55 53 5f 4c 4f 4f 4b 41 53 _DBSTATUS_LOOKAS
3aec0 49 44 45 5f 55 53 45 44 20 20 20 20 20 30 0a 0a IDE_USED 0..
3aed0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
3aee0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d Prepared Statem
3aef0 65 6e 74 20 53 74 61 74 75 73 20 7b 48 31 37 35 ent Status {H175
3af00 35 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 50} <S60200>.**
3af10 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a EXPERIMENTAL.**.
3af20 2a 2a 20 45 61 63 68 20 70 72 65 70 61 72 65 64 ** Each prepared
3af30 20 73 74 61 74 65 6d 65 6e 74 20 6d 61 69 6e 74 statement maint
3af40 61 69 6e 73 20 76 61 72 69 6f 75 73 0a 2a 2a 20 ains various.**
3af50 5b 53 51 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 [SQLITE_STMTSTAT
3af60 55 53 5f 53 4f 52 54 20 7c 20 63 6f 75 6e 74 65 US_SORT | counte
3af70 72 73 5d 20 74 68 61 74 20 6d 65 61 73 75 72 65 rs] that measure
3af80 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f the number.** o
3af90 66 20 74 69 6d 65 73 20 69 74 20 68 61 73 20 70 f times it has p
3afa0 65 72 66 6f 72 6d 65 64 20 73 70 65 63 69 66 69 erformed specifi
3afb0 63 20 6f 70 65 72 61 74 69 6f 6e 73 2e 20 20 54 c operations. T
3afc0 68 65 73 65 20 63 6f 75 6e 74 65 72 73 20 63 61 hese counters ca
3afd0 6e 0a 2a 2a 20 62 65 20 75 73 65 64 20 74 6f 20 n.** be used to
3afe0 6d 6f 6e 69 74 6f 72 20 74 68 65 20 70 65 72 66 monitor the perf
3aff0 6f 72 6d 61 6e 63 65 20 63 68 61 72 61 63 74 65 ormance characte
3b000 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 70 ristics of the p
3b010 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 repared.** state
3b020 6d 65 6e 74 73 2e 20 20 46 6f 72 20 65 78 61 6d ments. For exam
3b030 70 6c 65 2c 20 69 66 20 74 68 65 20 6e 75 6d 62 ple, if the numb
3b040 65 72 20 6f 66 20 74 61 62 6c 65 20 73 74 65 70 er of table step
3b050 73 20 67 72 65 61 74 6c 79 20 65 78 63 65 65 64 s greatly exceed
3b060 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 s.** the number
3b070 6f 66 20 74 61 62 6c 65 20 73 65 61 72 63 68 65 of table searche
3b080 73 20 6f 72 20 72 65 73 75 6c 74 20 72 6f 77 73 s or result rows
3b090 2c 20 74 68 61 74 20 77 6f 75 6c 64 20 74 65 6e , that would ten
3b0a0 64 20 74 6f 20 69 6e 64 69 63 61 74 65 0a 2a 2a d to indicate.**
3b0b0 20 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72 that the prepar
3b0c0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 ed statement is
3b0d0 75 73 69 6e 67 20 61 20 66 75 6c 6c 20 74 61 62 using a full tab
3b0e0 6c 65 20 73 63 61 6e 20 72 61 74 68 65 72 20 74 le scan rather t
3b0f0 68 61 6e 0a 2a 2a 20 61 6e 20 69 6e 64 65 78 2e han.** an index.
3b100 20 20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e .**.** This in
3b110 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 terface is used
3b120 74 6f 20 72 65 74 72 69 65 76 65 20 61 6e 64 20 to retrieve and
3b130 72 65 73 65 74 20 63 6f 75 6e 74 65 72 20 76 61 reset counter va
3b140 6c 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 61 20 5b lues from.** a [
3b150 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
3b160 6e 74 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 nt]. The first
3b170 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 argument is the
3b180 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
3b190 6e 74 0a 2a 2a 20 6f 62 6a 65 63 74 20 74 6f 20 nt.** object to
3b1a0 62 65 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e be interrogated.
3b1b0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 The second arg
3b1c0 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 61 6e 20 69 ument.** is an i
3b1d0 6e 74 65 67 65 72 20 63 6f 64 65 20 66 6f 72 20 nteger code for
3b1e0 61 20 73 70 65 63 69 66 69 63 20 5b 53 51 4c 49 a specific [SQLI
3b1f0 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f 53 4f TE_STMTSTATUS_SO
3b200 52 54 20 7c 20 63 6f 75 6e 74 65 72 5d 0a 2a 2a RT | counter].**
3b210 20 74 6f 20 62 65 20 69 6e 74 65 72 72 6f 67 61 to be interroga
3b220 74 65 64 2e 20 0a 2a 2a 20 54 68 65 20 63 75 72 ted. .** The cur
3b230 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 74 68 rent value of th
3b240 65 20 72 65 71 75 65 73 74 65 64 20 63 6f 75 6e e requested coun
3b250 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e ter is returned.
3b260 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 65 74 .** If the reset
3b270 46 6c 67 20 69 73 20 74 72 75 65 2c 20 74 68 65 Flg is true, the
3b280 6e 20 74 68 65 20 63 6f 75 6e 74 65 72 20 69 73 n the counter is
3b290 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 20 61 reset to zero a
3b2a0 66 74 65 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 fter this.** int
3b2b0 65 72 66 61 63 65 20 63 61 6c 6c 20 72 65 74 75 erface call retu
3b2c0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 rns..**.** See a
3b2d0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 73 74 lso: [sqlite3_st
3b2e0 61 74 75 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c atus()] and [sql
3b2f0 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 28 29 ite3_db_status()
3b300 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 ]..*/.SQLITE_API
3b310 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 SQLITE_EXPERIME
3b320 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 NTAL int sqlite3
3b330 5f 73 74 6d 74 5f 73 74 61 74 75 73 28 73 71 6c _stmt_status(sql
3b340 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
3b350 6f 70 2c 69 6e 74 20 72 65 73 65 74 46 6c 67 29 op,int resetFlg)
3b360 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
3b370 46 3a 20 53 74 61 74 75 73 20 50 61 72 61 6d 65 F: Status Parame
3b380 74 65 72 73 20 66 6f 72 20 70 72 65 70 61 72 65 ters for prepare
3b390 64 20 73 74 61 74 65 6d 65 6e 74 73 20 7b 48 31 d statements {H1
3b3a0 37 35 37 30 7d 20 3c 48 31 37 35 35 30 3e 0a 2a 7570} <H17550>.*
3b3b0 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a * EXPERIMENTAL.*
3b3c0 2a 0a 2a 2a 20 54 68 65 73 65 20 70 72 65 70 72 *.** These prepr
3b3d0 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 20 64 ocessor macros d
3b3e0 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f efine integer co
3b3f0 64 65 73 20 74 68 61 74 20 6e 61 6d 65 20 63 6f des that name co
3b400 75 6e 74 65 72 0a 2a 2a 20 76 61 6c 75 65 73 20 unter.** values
3b410 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
3b420 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d the [sqlite3_stm
3b430 74 5f 73 74 61 74 75 73 28 29 5d 20 69 6e 74 65 t_status()] inte
3b440 72 66 61 63 65 2e 0a 2a 2a 20 54 68 65 20 6d 65 rface..** The me
3b450 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 anings of the va
3b460 72 69 6f 75 73 20 63 6f 75 6e 74 65 72 73 20 61 rious counters a
3b470 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a re as follows:.*
3b480 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 *.** <dl>.** <dt
3b490 3e 53 51 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 >SQLITE_STMTSTAT
3b4a0 55 53 5f 46 55 4c 4c 53 43 41 4e 5f 53 54 45 50 US_FULLSCAN_STEP
3b4b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 </dt>.** <dd>Thi
3b4c0 73 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 s is the number
3b4d0 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 53 51 of times that SQ
3b4e0 4c 69 74 65 20 68 61 73 20 73 74 65 70 70 65 64 Lite has stepped
3b4f0 20 66 6f 72 77 61 72 64 20 69 6e 0a 2a 2a 20 61 forward in.** a
3b500 20 74 61 62 6c 65 20 61 73 20 70 61 72 74 20 6f table as part o
3b510 66 20 61 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 f a full table s
3b520 63 61 6e 2e 20 20 4c 61 72 67 65 20 6e 75 6d 62 can. Large numb
3b530 65 72 73 20 66 6f 72 20 74 68 69 73 20 63 6f 75 ers for this cou
3b540 6e 74 65 72 0a 2a 2a 20 6d 61 79 20 69 6e 64 69 nter.** may indi
3b550 63 61 74 65 20 6f 70 70 6f 72 74 75 6e 69 74 69 cate opportuniti
3b560 65 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e es for performan
3b570 63 65 20 69 6d 70 72 6f 76 65 6d 65 6e 74 20 74 ce improvement t
3b580 68 72 6f 75 67 68 20 0a 2a 2a 20 63 61 72 65 66 hrough .** caref
3b590 75 6c 20 75 73 65 20 6f 66 20 69 6e 64 69 63 65 ul use of indice
3b5a0 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 s.</dd>.**.** <d
3b5b0 74 3e 53 51 4c 49 54 45 5f 53 54 4d 54 53 54 41 t>SQLITE_STMTSTA
3b5c0 54 55 53 5f 53 4f 52 54 3c 2f 64 74 3e 0a 2a 2a TUS_SORT</dt>.**
3b5d0 20 3c 64 64 3e 54 68 69 73 20 69 73 20 74 68 65 <dd>This is the
3b5e0 20 6e 75 6d 62 65 72 20 6f 66 20 73 6f 72 74 20 number of sort
3b5f0 6f 70 65 72 61 74 69 6f 6e 73 20 74 68 61 74 20 operations that
3b600 68 61 76 65 20 6f 63 63 75 72 72 65 64 2e 0a 2a have occurred..*
3b610 2a 20 41 20 6e 6f 6e 2d 7a 65 72 6f 20 76 61 6c * A non-zero val
3b620 75 65 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 ue in this count
3b630 65 72 20 6d 61 79 20 69 6e 64 69 63 61 74 65 20 er may indicate
3b640 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 20 74 an opportunity t
3b650 6f 0a 2a 2a 20 69 6d 70 72 6f 76 65 6d 65 6e 74 o.** improvement
3b660 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 74 68 72 performance thr
3b670 6f 75 67 68 20 63 61 72 65 66 75 6c 20 75 73 65 ough careful use
3b680 20 6f 66 20 69 6e 64 69 63 65 73 2e 3c 2f 64 64 of indices.</dd
3b690 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f >.**.** </dl>.*/
3b6a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3b6b0 53 54 4d 54 53 54 41 54 55 53 5f 46 55 4c 4c 53 STMTSTATUS_FULLS
3b6c0 43 41 4e 5f 53 54 45 50 20 20 20 20 20 31 0a 23 CAN_STEP 1.#
3b6d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 define SQLITE_ST
3b6e0 4d 54 53 54 41 54 55 53 5f 53 4f 52 54 20 20 20 MTSTATUS_SORT
3b6f0 20 20 20 20 20 20 20 20 20 20 20 32 0a 0a 2f 2a 2../*
3b700 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 75 .** CAPI3REF: Cu
3b710 73 74 6f 6d 20 50 61 67 65 20 43 61 63 68 65 20 stom Page Cache
3b720 4f 62 6a 65 63 74 0a 2a 2a 20 45 58 50 45 52 49 Object.** EXPERI
3b730 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 MENTAL.**.** The
3b740 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 20 sqlite3_pcache
3b750 74 79 70 65 20 69 73 20 6f 70 61 71 75 65 2e 20 type is opaque.
3b760 20 49 74 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 It is implement
3b770 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 6c 75 ed by.** the plu
3b780 67 67 61 62 6c 65 20 6d 6f 64 75 6c 65 2e 20 20 ggable module.
3b790 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 The SQLite core
3b7a0 68 61 73 20 6e 6f 20 6b 6e 6f 77 6c 65 64 67 65 has no knowledge
3b7b0 20 6f 66 0a 2a 2a 20 69 74 73 20 73 69 7a 65 20 of.** its size
3b7c0 6f 72 20 69 6e 74 65 72 6e 61 6c 20 73 74 72 75 or internal stru
3b7d0 63 74 75 72 65 20 61 6e 64 20 6e 65 76 65 72 20 cture and never
3b7e0 64 65 61 6c 73 20 77 69 74 68 20 74 68 65 0a 2a deals with the.*
3b7f0 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 * sqlite3_pcache
3b800 20 6f 62 6a 65 63 74 20 65 78 63 65 70 74 20 62 object except b
3b810 79 20 68 6f 6c 64 69 6e 67 20 61 6e 64 20 70 61 y holding and pa
3b820 73 73 69 6e 67 20 70 6f 69 6e 74 65 72 73 0a 2a ssing pointers.*
3b830 2a 20 74 6f 20 74 68 65 20 6f 62 6a 65 63 74 2e * to the object.
3b840 0a 2a 2a 0a 2a 2a 20 53 65 65 20 5b 73 71 6c 69 .**.** See [sqli
3b850 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f te3_pcache_metho
3b860 64 73 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e ds] for addition
3b870 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a al information..
3b880 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
3b890 74 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 t sqlite3_pcache
3b8a0 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 3b sqlite3_pcache;
3b8b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
3b8c0 3a 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 44 65 : Application De
3b8d0 66 69 6e 65 64 20 50 61 67 65 20 43 61 63 68 65 fined Page Cache
3b8e0 2e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b ..** KEYWORDS: {
3b8f0 70 61 67 65 20 63 61 63 68 65 7d 0a 2a 2a 20 45 page cache}.** E
3b900 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a XPERIMENTAL.**.*
3b910 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 * The [sqlite3_c
3b920 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 onfig]([SQLITE_C
3b930 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 2c 20 2e ONFIG_PCACHE], .
3b940 2e 2e 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 ..) interface ca
3b950 6e 0a 2a 2a 20 72 65 67 69 73 74 65 72 20 61 6e n.** register an
3b960 20 61 6c 74 65 72 6e 61 74 69 76 65 20 70 61 67 alternative pag
3b970 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e e cache implemen
3b980 74 61 74 69 6f 6e 20 62 79 20 70 61 73 73 69 6e tation by passin
3b990 67 20 69 6e 20 61 6e 20 0a 2a 2a 20 69 6e 73 74 g in an .** inst
3b9a0 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 ance of the sqli
3b9b0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f te3_pcache_metho
3b9c0 64 73 20 73 74 72 75 63 74 75 72 65 2e 20 54 68 ds structure. Th
3b9d0 65 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 74 68 e majority of th
3b9e0 65 20 0a 2a 2a 20 68 65 61 70 20 6d 65 6d 6f 72 e .** heap memor
3b9f0 79 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 y used by SQLite
3ba00 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 is used by the
3ba10 70 61 67 65 20 63 61 63 68 65 20 74 6f 20 63 61 page cache to ca
3ba20 63 68 65 20 64 61 74 61 20 72 65 61 64 20 0a 2a che data read .*
3ba30 2a 20 66 72 6f 6d 2c 20 6f 72 20 72 65 61 64 79 * from, or ready
3ba40 20 74 6f 20 62 65 20 77 72 69 74 74 65 6e 20 74 to be written t
3ba50 6f 2c 20 74 68 65 20 64 61 74 61 62 61 73 65 20 o, the database
3ba60 66 69 6c 65 2e 20 42 79 20 69 6d 70 6c 65 6d 65 file. By impleme
3ba70 6e 74 69 6e 67 20 61 20 0a 2a 2a 20 63 75 73 74 nting a .** cust
3ba80 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 75 73 om page cache us
3ba90 69 6e 67 20 74 68 69 73 20 41 50 49 2c 20 61 6e ing this API, an
3baa0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e application can
3bab0 20 63 6f 6e 74 72 6f 6c 20 6d 6f 72 65 20 0a 2a control more .*
3bac0 2a 20 70 72 65 63 69 73 65 6c 79 20 74 68 65 20 * precisely the
3bad0 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 amount of memory
3bae0 20 63 6f 6e 73 75 6d 65 64 20 62 79 20 53 51 4c consumed by SQL
3baf0 69 74 65 2c 20 74 68 65 20 77 61 79 20 69 6e 20 ite, the way in
3bb00 77 68 69 63 68 20 0a 2a 2a 20 74 68 61 74 20 6d which .** that m
3bb10 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 emory is allocat
3bb20 65 64 20 61 6e 64 20 72 65 6c 65 61 73 65 64 2c ed and released,
3bb30 20 61 6e 64 20 74 68 65 20 70 6f 6c 69 63 69 65 and the policie
3bb40 73 20 75 73 65 64 20 74 6f 20 0a 2a 2a 20 64 65 s used to .** de
3bb50 74 65 72 6d 69 6e 65 20 65 78 61 63 74 6c 79 20 termine exactly
3bb60 77 68 69 63 68 20 70 61 72 74 73 20 6f 66 20 61 which parts of a
3bb70 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 database file a
3bb80 72 65 20 63 61 63 68 65 64 20 61 6e 64 20 66 6f re cached and fo
3bb90 72 20 0a 2a 2a 20 68 6f 77 20 6c 6f 6e 67 2e 0a r .** how long..
3bba0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 6e **.** The conten
3bbb0 74 73 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 ts of the sqlite
3bbc0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 3_pcache_methods
3bbd0 20 73 74 72 75 63 74 75 72 65 20 61 72 65 20 63 structure are c
3bbe0 6f 70 69 65 64 20 74 6f 20 61 6e 0a 2a 2a 20 69 opied to an.** i
3bbf0 6e 74 65 72 6e 61 6c 20 62 75 66 66 65 72 20 62 nternal buffer b
3bc00 79 20 53 51 4c 69 74 65 20 77 69 74 68 69 6e 20 y SQLite within
3bc10 74 68 65 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c the call to [sql
3bc20 69 74 65 33 5f 63 6f 6e 66 69 67 5d 2e 20 20 48 ite3_config]. H
3bc30 65 6e 63 65 0a 2a 2a 20 74 68 65 20 61 70 70 6c ence.** the appl
3bc40 69 63 61 74 69 6f 6e 20 6d 61 79 20 64 69 73 63 ication may disc
3bc50 61 72 64 20 74 68 65 20 70 61 72 61 6d 65 74 65 ard the paramete
3bc60 72 20 61 66 74 65 72 20 74 68 65 20 63 61 6c 6c r after the call
3bc70 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
3bc80 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e config()] return
3bc90 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e s..**.** The xIn
3bca0 69 74 28 29 20 6d 65 74 68 6f 64 20 69 73 20 63 it() method is c
3bcb0 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 alled once for e
3bcc0 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ach call to [sql
3bcd0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
3bce0 29 5d 0a 2a 2a 20 28 75 73 75 61 6c 6c 79 20 6f )].** (usually o
3bcf0 6e 6c 79 20 6f 6e 63 65 20 64 75 72 69 6e 67 20 nly once during
3bd00 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 the lifetime of
3bd10 74 68 65 20 70 72 6f 63 65 73 73 29 2e 20 49 74 the process). It
3bd20 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 61 20 is passed.** a
3bd30 63 6f 70 79 20 6f 66 20 74 68 65 20 73 71 6c 69 copy of the sqli
3bd40 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f te3_pcache_metho
3bd50 64 73 2e 70 41 72 67 20 76 61 6c 75 65 2e 20 49 ds.pArg value. I
3bd60 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f t can be used to
3bd70 20 73 65 74 0a 2a 2a 20 75 70 20 67 6c 6f 62 61 set.** up globa
3bd80 6c 20 73 74 72 75 63 74 75 72 65 73 20 61 6e 64 l structures and
3bd90 20 6d 75 74 65 78 65 73 20 72 65 71 75 69 72 65 mutexes require
3bda0 64 20 62 79 20 74 68 65 20 63 75 73 74 6f 6d 20 d by the custom
3bdb0 70 61 67 65 20 63 61 63 68 65 20 0a 2a 2a 20 69 page cache .** i
3bdc0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 0a mplementation. .
3bdd0 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 75 74 64 **.** The xShutd
3bde0 6f 77 6e 28 29 20 6d 65 74 68 6f 64 20 69 73 20 own() method is
3bdf0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 called from with
3be00 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 in [sqlite3_shut
3be10 64 6f 77 6e 28 29 5d 2c 20 0a 2a 2a 20 69 66 20 down()], .** if
3be20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
3be30 69 6e 76 6f 6b 65 73 20 74 68 69 73 20 41 50 49 invokes this API
3be40 2e 20 49 74 20 63 61 6e 20 62 65 20 75 73 65 64 . It can be used
3be50 20 74 6f 20 63 6c 65 61 6e 20 75 70 20 0a 2a 2a to clean up .**
3be60 20 61 6e 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 any outstanding
3be70 20 72 65 73 6f 75 72 63 65 73 20 62 65 66 6f 72 resources befor
3be80 65 20 70 72 6f 63 65 73 73 20 73 68 75 74 64 6f e process shutdo
3be90 77 6e 2c 20 69 66 20 72 65 71 75 69 72 65 64 2e wn, if required.
3bea0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f .**.** SQLite ho
3beb0 6c 64 73 20 61 20 5b 53 51 4c 49 54 45 5f 4d 55 lds a [SQLITE_MU
3bec0 54 45 58 5f 52 45 43 55 52 53 49 56 45 5d 20 6d TEX_RECURSIVE] m
3bed0 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 utex when it inv
3bee0 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 okes.** the xIni
3bef0 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 t method, so the
3bf00 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 xInit method ne
3bf10 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 ed not be thread
3bf20 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 safe. The.** xS
3bf30 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 hutdown method i
3bf40 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 s only called fr
3bf50 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 om [sqlite3_shut
3bf60 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f down()] so it do
3bf70 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 es.** not need t
3bf80 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 o be threadsafe
3bf90 65 69 74 68 65 72 2e 20 20 41 6c 6c 20 6f 74 68 either. All oth
3bfa0 65 72 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 er methods must
3bfb0 62 65 20 74 68 72 65 61 64 73 61 66 65 0a 2a 2a be threadsafe.**
3bfc0 20 69 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65 in multithreade
3bfd0 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 2e 0a d applications..
3bfe0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c **.** SQLite wil
3bff0 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 l never invoke x
3c000 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e Init() more than
3c010 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e once without an
3c020 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 intervening.**
3c030 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 call to xShutdow
3c040 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 n()..**.** The x
3c050 43 72 65 61 74 65 28 29 20 6d 65 74 68 6f 64 20 Create() method
3c060 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 73 74 is used to const
3c070 72 75 63 74 20 61 20 6e 65 77 20 63 61 63 68 65 ruct a new cache
3c080 20 69 6e 73 74 61 6e 63 65 2e 20 20 53 51 4c 69 instance. SQLi
3c090 74 65 0a 2a 2a 20 77 69 6c 6c 20 74 79 70 69 63 te.** will typic
3c0a0 61 6c 6c 79 20 63 72 65 61 74 65 20 6f 6e 65 20 ally create one
3c0b0 63 61 63 68 65 20 69 6e 73 74 61 6e 63 65 20 66 cache instance f
3c0c0 6f 72 20 65 61 63 68 20 6f 70 65 6e 20 64 61 74 or each open dat
3c0d0 61 62 61 73 65 20 66 69 6c 65 2c 0a 2a 2a 20 74 abase file,.** t
3c0e0 68 6f 75 67 68 20 74 68 69 73 20 69 73 20 6e 6f hough this is no
3c0f0 74 20 67 75 61 72 61 6e 74 65 65 64 2e 20 54 68 t guaranteed. Th
3c100 65 0a 2a 2a 20 66 69 72 73 74 20 70 61 72 61 6d e.** first param
3c110 65 74 65 72 2c 20 73 7a 50 61 67 65 2c 20 69 73 eter, szPage, is
3c120 20 74 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 the size in byt
3c130 65 73 20 6f 66 20 74 68 65 20 70 61 67 65 73 20 es of the pages
3c140 74 68 61 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 that must.** be
3c150 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 74 68 65 allocated by the
3c160 20 63 61 63 68 65 2e 20 20 73 7a 50 61 67 65 20 cache. szPage
3c170 77 69 6c 6c 20 6e 6f 74 20 62 65 20 61 20 70 6f will not be a po
3c180 77 65 72 20 6f 66 20 74 77 6f 2e 20 20 73 7a 50 wer of two. szP
3c190 61 67 65 0a 2a 2a 20 77 69 6c 6c 20 74 68 65 20 age.** will the
3c1a0 70 61 67 65 20 73 69 7a 65 20 6f 66 20 74 68 65 page size of the
3c1b0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 database file t
3c1c0 68 61 74 20 69 73 20 74 6f 20 62 65 20 63 61 63 hat is to be cac
3c1d0 68 65 64 20 70 6c 75 73 20 61 6e 0a 2a 2a 20 69 hed plus an.** i
3c1e0 6e 63 72 65 6d 65 6e 74 20 28 68 65 72 65 20 63 ncrement (here c
3c1f0 61 6c 6c 65 64 20 22 52 22 29 20 6f 66 20 61 62 alled "R") of ab
3c200 6f 75 74 20 31 30 30 20 6f 72 20 32 30 30 2e 20 out 100 or 200.
3c210 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 SQLite will use
3c220 20 74 68 65 0a 2a 2a 20 65 78 74 72 61 20 52 20 the.** extra R
3c230 62 79 74 65 73 20 6f 6e 20 65 61 63 68 20 70 61 bytes on each pa
3c240 67 65 20 74 6f 20 73 74 6f 72 65 20 6d 65 74 61 ge to store meta
3c250 64 61 74 61 20 61 62 6f 75 74 20 74 68 65 20 75 data about the u
3c260 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a 20 64 61 74 nderlying.** dat
3c270 61 62 61 73 65 20 70 61 67 65 20 6f 6e 20 64 69 abase page on di
3c280 73 6b 2e 20 20 54 68 65 20 76 61 6c 75 65 20 6f sk. The value o
3c290 66 20 52 20 64 65 70 65 6e 64 73 0a 2a 2a 20 6f f R depends.** o
3c2a0 6e 20 74 68 65 20 53 51 4c 69 74 65 20 76 65 72 n the SQLite ver
3c2b0 73 69 6f 6e 2c 20 74 68 65 20 74 61 72 67 65 74 sion, the target
3c2c0 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20 68 platform, and h
3c2d0 6f 77 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f ow SQLite was co
3c2e0 6d 70 69 6c 65 64 2e 0a 2a 2a 20 52 20 69 73 20 mpiled..** R is
3c2f0 63 6f 6e 73 74 61 6e 74 20 66 6f 72 20 61 20 70 constant for a p
3c300 61 72 74 69 63 75 6c 61 72 20 62 75 69 6c 64 20 articular build
3c310 6f 66 20 53 51 4c 69 74 65 2e 20 20 54 68 65 20 of SQLite. The
3c320 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
3c330 74 6f 0a 2a 2a 20 78 43 72 65 61 74 65 28 29 2c to.** xCreate(),
3c340 20 62 50 75 72 67 65 61 62 6c 65 2c 20 69 73 20 bPurgeable, is
3c350 74 72 75 65 20 69 66 20 74 68 65 20 63 61 63 68 true if the cach
3c360 65 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 20 e being created
3c370 77 69 6c 6c 0a 2a 2a 20 62 65 20 75 73 65 64 20 will.** be used
3c380 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 73 to cache databas
3c390 65 20 70 61 67 65 73 20 6f 66 20 61 20 66 69 6c e pages of a fil
3c3a0 65 20 73 74 6f 72 65 64 20 6f 6e 20 64 69 73 6b e stored on disk
3c3b0 2c 20 6f 72 0a 2a 2a 20 66 61 6c 73 65 20 69 66 , or.** false if
3c3c0 20 69 74 20 69 73 20 75 73 65 64 20 66 6f 72 20 it is used for
3c3d0 61 6e 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 an in-memory dat
3c3e0 61 62 61 73 65 2e 20 54 68 65 20 63 61 63 68 65 abase. The cache
3c3f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a implementation.
3c400 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 ** does not have
3c410 20 74 6f 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 to do anything
3c420 73 70 65 63 69 61 6c 20 62 61 73 65 64 20 77 69 special based wi
3c430 74 68 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 th the value of
3c440 62 50 75 72 67 65 61 62 6c 65 3b 0a 2a 2a 20 69 bPurgeable;.** i
3c450 74 20 69 73 20 70 75 72 65 6c 79 20 61 64 76 69 t is purely advi
3c460 73 6f 72 79 2e 20 20 4f 6e 20 61 20 63 61 63 68 sory. On a cach
3c470 65 20 77 68 65 72 65 20 62 50 75 72 67 65 61 62 e where bPurgeab
3c480 6c 65 20 69 73 20 66 61 6c 73 65 2c 20 53 51 4c le is false, SQL
3c490 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65 ite will.** neve
3c4a0 72 20 69 6e 76 6f 6b 65 20 78 55 6e 70 69 6e 28 r invoke xUnpin(
3c4b0 29 20 65 78 63 65 70 74 20 74 6f 20 64 65 6c 69 ) except to deli
3c4c0 62 65 72 61 74 65 6c 79 20 64 65 6c 65 74 65 20 berately delete
3c4d0 61 20 70 61 67 65 2e 0a 2a 2a 20 49 6e 20 6f 74 a page..** In ot
3c4e0 68 65 72 20 77 6f 72 64 73 2c 20 61 20 63 61 63 her words, a cac
3c4f0 68 65 20 63 72 65 61 74 65 64 20 77 69 74 68 20 he created with
3c500 62 50 75 72 67 65 61 62 6c 65 20 73 65 74 20 74 bPurgeable set t
3c510 6f 20 66 61 6c 73 65 20 77 69 6c 6c 0a 2a 2a 20 o false will.**
3c520 6e 65 76 65 72 20 63 6f 6e 74 61 69 6e 20 61 6e never contain an
3c530 79 20 75 6e 70 69 6e 6e 65 64 20 70 61 67 65 73 y unpinned pages
3c540 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 43 61 63 ..**.** The xCac
3c550 68 65 73 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 hesize() method
3c560 6d 61 79 20 62 65 20 63 61 6c 6c 65 64 20 61 74 may be called at
3c570 20 61 6e 79 20 74 69 6d 65 20 62 79 20 53 51 4c any time by SQL
3c580 69 74 65 20 74 6f 20 73 65 74 20 74 68 65 0a 2a ite to set the.*
3c590 2a 20 73 75 67 67 65 73 74 65 64 20 6d 61 78 69 * suggested maxi
3c5a0 6d 75 6d 20 63 61 63 68 65 2d 73 69 7a 65 20 28 mum cache-size (
3c5b0 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 number of pages
3c5c0 73 74 6f 72 65 64 20 62 79 29 20 74 68 65 20 63 stored by) the c
3c5d0 61 63 68 65 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 ache.** instance
3c5e0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 passed as the f
3c5f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 54 irst argument. T
3c600 68 69 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 his is the value
3c610 20 63 6f 6e 66 69 67 75 72 65 64 20 75 73 69 6e configured usin
3c620 67 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 g.** the SQLite
3c630 22 5b 50 52 41 47 4d 41 20 63 61 63 68 65 5f 73 "[PRAGMA cache_s
3c640 69 7a 65 5d 22 20 63 6f 6d 6d 61 6e 64 2e 20 41 ize]" command. A
3c650 73 20 77 69 74 68 20 74 68 65 20 62 50 75 72 67 s with the bPurg
3c660 65 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72 2c eable parameter,
3c670 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e .** the implemen
3c680 74 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 72 65 tation is not re
3c690 71 75 69 72 65 64 20 74 6f 20 64 6f 20 61 6e 79 quired to do any
3c6a0 74 68 69 6e 67 20 77 69 74 68 20 74 68 69 73 0a thing with this.
3c6b0 2a 2a 20 76 61 6c 75 65 3b 20 69 74 20 69 73 20 ** value; it is
3c6c0 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a advisory only..*
3c6d0 2a 0a 2a 2a 20 54 68 65 20 78 50 61 67 65 63 6f *.** The xPageco
3c6e0 75 6e 74 28 29 20 6d 65 74 68 6f 64 20 73 68 6f unt() method sho
3c6f0 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 6e uld return the n
3c700 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 63 umber of pages c
3c710 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 73 74 6f 72 urrently.** stor
3c720 65 64 20 69 6e 20 74 68 65 20 63 61 63 68 65 2e ed in the cache.
3c730 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 78 46 65 74 .** .** The xFet
3c740 63 68 28 29 20 6d 65 74 68 6f 64 20 69 73 20 75 ch() method is u
3c750 73 65 64 20 74 6f 20 66 65 74 63 68 20 61 20 70 sed to fetch a p
3c760 61 67 65 20 61 6e 64 20 72 65 74 75 72 6e 20 61 age and return a
3c770 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e 20 pointer to it.
3c780 0a 2a 2a 20 41 20 27 70 61 67 65 27 2c 20 69 6e .** A 'page', in
3c790 20 74 68 69 73 20 63 6f 6e 74 65 78 74 2c 20 69 this context, i
3c7a0 73 20 61 20 62 75 66 66 65 72 20 6f 66 20 73 7a s a buffer of sz
3c7b0 50 61 67 65 20 62 79 74 65 73 20 61 6c 69 67 6e Page bytes align
3c7c0 65 64 20 61 74 20 61 6e 0a 2a 2a 20 38 2d 62 79 ed at an.** 8-by
3c7d0 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 54 68 65 te boundary. The
3c7e0 20 70 61 67 65 20 74 6f 20 62 65 20 66 65 74 63 page to be fetc
3c7f0 68 65 64 20 69 73 20 64 65 74 65 72 6d 69 6e 65 hed is determine
3c800 64 20 62 79 20 74 68 65 20 6b 65 79 2e 20 54 68 d by the key. Th
3c810 65 0a 2a 2a 20 6d 69 6d 69 6d 75 6d 20 6b 65 79 e.** mimimum key
3c820 20 76 61 6c 75 65 20 69 73 20 31 2e 20 41 66 74 value is 1. Aft
3c830 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 er it has been r
3c840 65 74 72 69 65 76 65 64 20 75 73 69 6e 67 20 78 etrieved using x
3c850 46 65 74 63 68 2c 20 74 68 65 20 70 61 67 65 20 Fetch, the page
3c860 0a 2a 2a 20 69 73 20 63 6f 6e 73 69 64 65 72 65 .** is considere
3c870 64 20 74 6f 20 62 65 20 22 70 69 6e 6e 65 64 22 d to be "pinned"
3c880 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 ..**.** If the r
3c890 65 71 75 65 73 74 65 64 20 70 61 67 65 20 69 73 equested page is
3c8a0 20 61 6c 72 65 61 64 79 20 69 6e 20 74 68 65 20 already in the
3c8b0 70 61 67 65 20 63 61 63 68 65 2c 20 74 68 65 6e page cache, then
3c8c0 20 74 68 65 20 70 61 67 65 20 63 61 63 68 65 0a the page cache.
3c8d0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
3c8e0 6e 20 6d 75 73 74 20 72 65 74 75 72 6e 20 61 20 n must return a
3c8f0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 70 pointer to the p
3c900 61 67 65 20 62 75 66 66 65 72 20 77 69 74 68 20 age buffer with
3c910 69 74 73 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 69 its content.** i
3c920 6e 74 61 63 74 2e 20 20 49 66 20 74 68 65 20 72 ntact. If the r
3c930 65 71 75 65 73 74 65 64 20 70 61 67 65 20 69 73 equested page is
3c940 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 69 6e 20 not already in
3c950 74 68 65 20 63 61 63 68 65 2c 20 74 68 65 6e 20 the cache, then
3c960 74 68 65 0a 2a 2a 20 62 65 68 61 76 69 6f 72 20 the.** behavior
3c970 6f 66 20 74 68 65 20 63 61 63 68 65 20 69 6d 70 of the cache imp
3c980 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 64 lementation is d
3c990 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 etermined by the
3c9a0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a value of the.**
3c9b0 20 63 72 65 61 74 65 46 6c 61 67 20 70 61 72 61 createFlag para
3c9c0 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 meter passed to
3c9d0 78 46 65 74 63 68 2c 20 61 63 63 6f 72 64 69 6e xFetch, accordin
3c9e0 67 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 g to the followi
3c9f0 6e 67 20 74 61 62 6c 65 3a 0a 2a 2a 0a 2a 2a 20 ng table:.**.**
3ca00 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 31 20 <table border=1
3ca10 77 69 64 74 68 3d 38 35 25 20 61 6c 69 67 6e 3d width=85% align=
3ca20 63 65 6e 74 65 72 3e 0a 2a 2a 20 3c 74 72 3e 3c center>.** <tr><
3ca30 74 68 3e 20 63 72 65 61 74 65 46 6c 61 67 20 3c th> createFlag <
3ca40 74 68 3e 20 42 65 68 61 76 69 6f 75 72 20 77 68 th> Behaviour wh
3ca50 65 6e 20 70 61 67 65 20 69 73 20 6e 6f 74 20 61 en page is not a
3ca60 6c 72 65 61 64 79 20 69 6e 20 63 61 63 68 65 0a lready in cache.
3ca70 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 30 20 3c 74 ** <tr><td> 0 <t
3ca80 64 3e 20 44 6f 20 6e 6f 74 20 61 6c 6c 6f 63 61 d> Do not alloca
3ca90 74 65 20 61 20 6e 65 77 20 70 61 67 65 2e 20 20 te a new page.
3caa0 52 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a 20 Return NULL..**
3cab0 3c 74 72 3e 3c 74 64 3e 20 31 20 3c 74 64 3e 20 <tr><td> 1 <td>
3cac0 41 6c 6c 6f 63 61 74 65 20 61 20 6e 65 77 20 70 Allocate a new p
3cad0 61 67 65 20 69 66 20 69 74 20 65 61 73 79 20 61 age if it easy a
3cae0 6e 64 20 63 6f 6e 76 65 6e 69 65 6e 74 20 74 6f nd convenient to
3caf0 20 64 6f 20 73 6f 2e 0a 2a 2a 20 20 20 20 20 20 do so..**
3cb00 20 20 20 20 20 20 20 20 20 20 20 4f 74 68 65 72 Other
3cb10 77 69 73 65 20 72 65 74 75 72 6e 20 4e 55 4c 4c wise return NULL
3cb20 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 32 20 ..** <tr><td> 2
3cb30 3c 74 64 3e 20 4d 61 6b 65 20 65 76 65 72 79 20 <td> Make every
3cb40 65 66 66 6f 72 74 20 74 6f 20 61 6c 6c 6f 63 61 effort to alloca
3cb50 74 65 20 61 20 6e 65 77 20 70 61 67 65 2e 20 20 te a new page.
3cb60 4f 6e 6c 79 20 72 65 74 75 72 6e 0a 2a 2a 20 20 Only return.**
3cb70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 4e N
3cb80 55 4c 4c 20 69 66 20 61 6c 6c 6f 63 61 74 69 6e ULL if allocatin
3cb90 67 20 61 20 6e 65 77 20 70 61 67 65 20 69 73 20 g a new page is
3cba0 65 66 66 65 63 74 69 76 65 6c 79 20 69 6d 70 6f effectively impo
3cbb0 73 73 69 62 6c 65 2e 0a 2a 2a 20 3c 2f 74 61 62 ssible..** </tab
3cbc0 6c 65 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 le>.**.** SQLite
3cbd0 20 77 69 6c 6c 20 6e 6f 72 6d 61 6c 6c 79 20 69 will normally i
3cbe0 6e 76 6f 6b 65 20 78 46 65 74 63 68 28 29 20 77 nvoke xFetch() w
3cbf0 69 74 68 20 61 20 63 72 65 61 74 65 46 6c 61 67 ith a createFlag
3cc00 20 6f 66 20 30 20 6f 72 20 31 2e 20 20 49 66 0a of 0 or 1. If.
3cc10 2a 2a 20 61 20 63 61 6c 6c 20 74 6f 20 78 46 65 ** a call to xFe
3cc20 74 63 68 28 29 20 77 69 74 68 20 63 72 65 61 74 tch() with creat
3cc30 65 46 6c 61 67 3d 3d 31 20 72 65 74 75 72 6e 73 eFlag==1 returns
3cc40 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 NULL, then SQLi
3cc50 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 74 74 65 6d te will.** attem
3cc60 70 74 20 74 6f 20 75 6e 70 69 6e 20 6f 6e 65 20 pt to unpin one
3cc70 6f 72 20 6d 6f 72 65 20 63 61 63 68 65 20 70 61 or more cache pa
3cc80 67 65 73 20 62 79 20 73 70 69 6c 6c 69 6e 67 20 ges by spilling
3cc90 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 0a 2a the content of.*
3cca0 2a 20 70 69 6e 6e 65 64 20 70 61 67 65 73 20 74 * pinned pages t
3ccb0 6f 20 64 69 73 6b 20 61 6e 64 20 73 79 6e 63 68 o disk and synch
3ccc0 69 6e 67 20 74 68 65 20 6f 70 65 72 61 74 69 6e ing the operatin
3ccd0 67 20 73 79 73 74 65 6d 20 64 69 73 6b 20 63 61 g system disk ca
3cce0 63 68 65 2e 20 41 66 74 65 72 0a 2a 2a 20 61 74 che. After.** at
3ccf0 74 65 6d 70 74 69 6e 67 20 74 6f 20 75 6e 70 69 tempting to unpi
3cd00 6e 20 70 61 67 65 73 2c 20 74 68 65 20 78 46 65 n pages, the xFe
3cd10 74 63 68 28 29 20 6d 65 74 68 6f 64 20 77 69 6c tch() method wil
3cd20 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 61 67 61 l be invoked aga
3cd30 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 63 72 65 in with.** a cre
3cd40 61 74 65 46 6c 61 67 20 6f 66 20 32 2e 0a 2a 2a ateFlag of 2..**
3cd50 0a 2a 2a 20 78 55 6e 70 69 6e 28 29 20 69 73 20 .** xUnpin() is
3cd60 63 61 6c 6c 65 64 20 62 79 20 53 51 4c 69 74 65 called by SQLite
3cd70 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 with a pointer
3cd80 74 6f 20 61 20 63 75 72 72 65 6e 74 6c 79 20 70 to a currently p
3cd90 69 6e 6e 65 64 20 70 61 67 65 0a 2a 2a 20 61 73 inned page.** as
3cda0 20 69 74 73 20 73 65 63 6f 6e 64 20 61 72 67 75 its second argu
3cdb0 6d 65 6e 74 2e 20 49 66 20 74 68 65 20 74 68 69 ment. If the thi
3cdc0 72 64 20 70 61 72 61 6d 65 74 65 72 2c 20 64 69 rd parameter, di
3cdd0 73 63 61 72 64 2c 20 69 73 20 6e 6f 6e 2d 7a 65 scard, is non-ze
3cde0 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 ro,.** then the
3cdf0 70 61 67 65 20 73 68 6f 75 6c 64 20 62 65 20 65 page should be e
3ce00 76 69 63 74 65 64 20 66 72 6f 6d 20 74 68 65 20 victed from the
3ce10 63 61 63 68 65 2e 20 49 6e 20 74 68 69 73 20 63 cache. In this c
3ce20 61 73 65 20 53 51 4c 69 74 65 20 0a 2a 2a 20 61 ase SQLite .** a
3ce30 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 ssumes that the
3ce40 6e 65 78 74 20 74 69 6d 65 20 74 68 65 20 70 61 next time the pa
3ce50 67 65 20 69 73 20 72 65 74 72 69 65 76 65 64 20 ge is retrieved
3ce60 66 72 6f 6d 20 74 68 65 20 63 61 63 68 65 20 75 from the cache u
3ce70 73 69 6e 67 0a 2a 2a 20 74 68 65 20 78 46 65 74 sing.** the xFet
3ce80 63 68 28 29 20 6d 65 74 68 6f 64 2c 20 69 74 20 ch() method, it
3ce90 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e 20 will be zeroed.
3cea0 49 66 20 74 68 65 20 64 69 73 63 61 72 64 20 70 If the discard p
3ceb0 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 7a arameter is.** z
3cec0 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 70 61 ero, then the pa
3ced0 67 65 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 ge is considered
3cee0 20 74 6f 20 62 65 20 75 6e 70 69 6e 6e 65 64 2e to be unpinned.
3cef0 20 54 68 65 20 63 61 63 68 65 20 69 6d 70 6c 65 The cache imple
3cf00 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6d 61 79 mentation.** may
3cf10 20 63 68 6f 6f 73 65 20 74 6f 20 65 76 69 63 74 choose to evict
3cf20 20 75 6e 70 69 6e 6e 65 64 20 70 61 67 65 73 20 unpinned pages
3cf30 61 74 20 61 6e 79 20 74 69 6d 65 2e 0a 2a 2a 0a at any time..**.
3cf40 2a 2a 20 54 68 65 20 63 61 63 68 65 20 69 73 20 ** The cache is
3cf50 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 not required to
3cf60 70 65 72 66 6f 72 6d 20 61 6e 79 20 72 65 66 65 perform any refe
3cf70 72 65 6e 63 65 20 63 6f 75 6e 74 69 6e 67 2e 20 rence counting.
3cf80 41 20 73 69 6e 67 6c 65 20 0a 2a 2a 20 63 61 6c A single .** cal
3cf90 6c 20 74 6f 20 78 55 6e 70 69 6e 28 29 20 75 6e l to xUnpin() un
3cfa0 70 69 6e 73 20 74 68 65 20 70 61 67 65 20 72 65 pins the page re
3cfb0 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 gardless of the
3cfc0 6e 75 6d 62 65 72 20 6f 66 20 70 72 69 6f 72 20 number of prior
3cfd0 63 61 6c 6c 73 20 0a 2a 2a 20 74 6f 20 78 46 65 calls .** to xFe
3cfe0 74 63 68 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 tch()..**.** The
3cff0 20 78 52 65 6b 65 79 28 29 20 6d 65 74 68 6f 64 xRekey() method
3d000 20 69 73 20 75 73 65 64 20 74 6f 20 63 68 61 6e is used to chan
3d010 67 65 20 74 68 65 20 6b 65 79 20 76 61 6c 75 65 ge the key value
3d020 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
3d030 20 74 68 65 0a 2a 2a 20 70 61 67 65 20 70 61 73 the.** page pas
3d040 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e sed as the secon
3d050 64 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 d argument from
3d060 6f 6c 64 4b 65 79 20 74 6f 20 6e 65 77 4b 65 79 oldKey to newKey
3d070 2e 20 49 66 20 74 68 65 20 63 61 63 68 65 0a 2a . If the cache.*
3d080 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6f 6e * previously con
3d090 74 61 69 6e 73 20 61 6e 20 65 6e 74 72 79 20 61 tains an entry a
3d0a0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 6e ssociated with n
3d0b0 65 77 4b 65 79 2c 20 69 74 20 73 68 6f 75 6c 64 ewKey, it should
3d0c0 20 62 65 0a 2a 2a 20 64 69 73 63 61 72 64 65 64 be.** discarded
3d0d0 2e 20 41 6e 79 20 70 72 69 6f 72 20 63 61 63 68 . Any prior cach
3d0e0 65 20 65 6e 74 72 79 20 61 73 73 6f 63 69 61 74 e entry associat
3d0f0 65 64 20 77 69 74 68 20 6e 65 77 4b 65 79 20 69 ed with newKey i
3d100 73 20 67 75 61 72 61 6e 74 65 65 64 20 6e 6f 74 s guaranteed not
3d110 0a 2a 2a 20 74 6f 20 62 65 20 70 69 6e 6e 65 64 .** to be pinned
3d120 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c ..**.** When SQL
3d130 69 74 65 20 63 61 6c 6c 73 20 74 68 65 20 78 54 ite calls the xT
3d140 72 75 6e 63 61 74 65 28 29 20 6d 65 74 68 6f 64 runcate() method
3d150 2c 20 74 68 65 20 63 61 63 68 65 20 6d 75 73 74 , the cache must
3d160 20 64 69 73 63 61 72 64 20 61 6c 6c 0a 2a 2a 20 discard all.**
3d170 65 78 69 73 74 69 6e 67 20 63 61 63 68 65 20 65 existing cache e
3d180 6e 74 72 69 65 73 20 77 69 74 68 20 70 61 67 65 ntries with page
3d190 20 6e 75 6d 62 65 72 73 20 28 6b 65 79 73 29 20 numbers (keys)
3d1a0 67 72 65 61 74 65 72 20 74 68 61 6e 20 6f 72 20 greater than or
3d1b0 65 71 75 61 6c 0a 2a 2a 20 74 6f 20 74 68 65 20 equal.** to the
3d1c0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 4c 69 value of the iLi
3d1d0 6d 69 74 20 70 61 72 61 6d 65 74 65 72 20 70 61 mit parameter pa
3d1e0 73 73 65 64 20 74 6f 20 78 54 72 75 6e 63 61 74 ssed to xTruncat
3d1f0 65 28 29 2e 20 49 66 20 61 6e 79 0a 2a 2a 20 6f e(). If any.** o
3d200 66 20 74 68 65 73 65 20 70 61 67 65 73 20 61 72 f these pages ar
3d210 65 20 70 69 6e 6e 65 64 2c 20 74 68 65 79 20 61 e pinned, they a
3d220 72 65 20 69 6d 70 6c 69 63 69 74 6c 79 20 75 6e re implicitly un
3d230 70 69 6e 6e 65 64 2c 20 6d 65 61 6e 69 6e 67 20 pinned, meaning
3d240 74 68 61 74 0a 2a 2a 20 74 68 65 79 20 63 61 6e that.** they can
3d250 20 62 65 20 73 61 66 65 6c 79 20 64 69 73 63 61 be safely disca
3d260 72 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 rded..**.** The
3d270 78 44 65 73 74 72 6f 79 28 29 20 6d 65 74 68 6f xDestroy() metho
3d280 64 20 69 73 20 75 73 65 64 20 74 6f 20 64 65 6c d is used to del
3d290 65 74 65 20 61 20 63 61 63 68 65 20 61 6c 6c 6f ete a cache allo
3d2a0 63 61 74 65 64 20 62 79 20 78 43 72 65 61 74 65 cated by xCreate
3d2b0 28 29 2e 0a 2a 2a 20 41 6c 6c 20 72 65 73 6f 75 ()..** All resou
3d2c0 72 63 65 73 20 61 73 73 6f 63 69 61 74 65 64 20 rces associated
3d2d0 77 69 74 68 20 74 68 65 20 73 70 65 63 69 66 69 with the specifi
3d2e0 65 64 20 63 61 63 68 65 20 73 68 6f 75 6c 64 20 ed cache should
3d2f0 62 65 20 66 72 65 65 64 2e 20 41 66 74 65 72 0a be freed. After.
3d300 2a 2a 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 ** calling the x
3d310 44 65 73 74 72 6f 79 28 29 20 6d 65 74 68 6f 64 Destroy() method
3d320 2c 20 53 51 4c 69 74 65 20 63 6f 6e 73 69 64 65 , SQLite conside
3d330 72 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f rs the [sqlite3_
3d340 70 63 61 63 68 65 2a 5d 0a 2a 2a 20 68 61 6e 64 pcache*].** hand
3d350 6c 65 20 69 6e 76 61 6c 69 64 2c 20 61 6e 64 20 le invalid, and
3d360 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20 69 74 20 will not use it
3d370 77 69 74 68 20 61 6e 79 20 6f 74 68 65 72 20 73 with any other s
3d380 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 qlite3_pcache_me
3d390 74 68 6f 64 73 0a 2a 2a 20 66 75 6e 63 74 69 6f thods.** functio
3d3a0 6e 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 ns..*/.typedef s
3d3b0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 70 63 truct sqlite3_pc
3d3c0 61 63 68 65 5f 6d 65 74 68 6f 64 73 20 73 71 6c ache_methods sql
3d3d0 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 ite3_pcache_meth
3d3e0 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 ods;.struct sqli
3d3f0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f te3_pcache_metho
3d400 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 70 41 72 ds {. void *pAr
3d410 67 3b 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 g;. int (*xInit
3d420 29 28 76 6f 69 64 2a 29 3b 0a 20 20 76 6f 69 64 )(void*);. void
3d430 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f (*xShutdown)(vo
3d440 69 64 2a 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f id*);. sqlite3_
3d450 70 63 61 63 68 65 20 2a 28 2a 78 43 72 65 61 74 pcache *(*xCreat
3d460 65 29 28 69 6e 74 20 73 7a 50 61 67 65 2c 20 69 e)(int szPage, i
3d470 6e 74 20 62 50 75 72 67 65 61 62 6c 65 29 3b 0a nt bPurgeable);.
3d480 20 20 76 6f 69 64 20 28 2a 78 43 61 63 68 65 73 void (*xCaches
3d490 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 70 63 61 ize)(sqlite3_pca
3d4a0 63 68 65 2a 2c 20 69 6e 74 20 6e 43 61 63 68 65 che*, int nCache
3d4b0 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 size);. int (*x
3d4c0 50 61 67 65 63 6f 75 6e 74 29 28 73 71 6c 69 74 Pagecount)(sqlit
3d4d0 65 33 5f 70 63 61 63 68 65 2a 29 3b 0a 20 20 76 e3_pcache*);. v
3d4e0 6f 69 64 20 2a 28 2a 78 46 65 74 63 68 29 28 73 oid *(*xFetch)(s
3d4f0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 2a 2c 20 qlite3_pcache*,
3d500 75 6e 73 69 67 6e 65 64 20 6b 65 79 2c 20 69 6e unsigned key, in
3d510 74 20 63 72 65 61 74 65 46 6c 61 67 29 3b 0a 20 t createFlag);.
3d520 20 76 6f 69 64 20 28 2a 78 55 6e 70 69 6e 29 28 void (*xUnpin)(
3d530 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 2a 2c sqlite3_pcache*,
3d540 20 76 6f 69 64 2a 2c 20 69 6e 74 20 64 69 73 63 void*, int disc
3d550 61 72 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 ard);. void (*x
3d560 52 65 6b 65 79 29 28 73 71 6c 69 74 65 33 5f 70 Rekey)(sqlite3_p
3d570 63 61 63 68 65 2a 2c 20 76 6f 69 64 2a 2c 20 75 cache*, void*, u
3d580 6e 73 69 67 6e 65 64 20 6f 6c 64 4b 65 79 2c 20 nsigned oldKey,
3d590 75 6e 73 69 67 6e 65 64 20 6e 65 77 4b 65 79 29 unsigned newKey)
3d5a0 3b 0a 20 20 76 6f 69 64 20 28 2a 78 54 72 75 6e ;. void (*xTrun
3d5b0 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 70 63 cate)(sqlite3_pc
3d5c0 61 63 68 65 2a 2c 20 75 6e 73 69 67 6e 65 64 20 ache*, unsigned
3d5d0 69 4c 69 6d 69 74 29 3b 0a 20 20 76 6f 69 64 20 iLimit);. void
3d5e0 28 2a 78 44 65 73 74 72 6f 79 29 28 73 71 6c 69 (*xDestroy)(sqli
3d5f0 74 65 33 5f 70 63 61 63 68 65 2a 29 3b 0a 7d 3b te3_pcache*);.};
3d600 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
3d610 3a 20 4f 6e 6c 69 6e 65 20 42 61 63 6b 75 70 20 : Online Backup
3d620 4f 62 6a 65 63 74 0a 2a 2a 20 45 58 50 45 52 49 Object.** EXPERI
3d630 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 MENTAL.**.** The
3d640 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 sqlite3_backup
3d650 6f 62 6a 65 63 74 20 72 65 63 6f 72 64 73 20 73 object records s
3d660 74 61 74 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e tate information
3d670 20 61 62 6f 75 74 20 61 6e 20 6f 6e 67 6f 69 6e about an ongoin
3d680 67 0a 2a 2a 20 6f 6e 6c 69 6e 65 20 62 61 63 6b g.** online back
3d690 75 70 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 54 up operation. T
3d6a0 68 65 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 he sqlite3_backu
3d6b0 70 20 6f 62 6a 65 63 74 20 69 73 20 63 72 65 61 p object is crea
3d6c0 74 65 64 20 62 79 0a 2a 2a 20 61 20 63 61 6c 6c ted by.** a call
3d6d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 to [sqlite3_bac
3d6e0 6b 75 70 5f 69 6e 69 74 28 29 5d 20 61 6e 64 20 kup_init()] and
3d6f0 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 is destroyed by
3d700 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 a call to.** [sq
3d710 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e lite3_backup_fin
3d720 69 73 68 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 ish()]..**.** Se
3d730 65 20 41 6c 73 6f 3a 20 5b 55 73 69 6e 67 20 74 e Also: [Using t
3d740 68 65 20 53 51 4c 69 74 65 20 4f 6e 6c 69 6e 65 he SQLite Online
3d750 20 42 61 63 6b 75 70 20 41 50 49 5d 0a 2a 2f 0a Backup API].*/.
3d760 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
3d770 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 73 71 qlite3_backup sq
3d780 6c 69 74 65 33 5f 62 61 63 6b 75 70 3b 0a 0a 2f lite3_backup;../
3d790 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
3d7a0 6e 6c 69 6e 65 20 42 61 63 6b 75 70 20 41 50 49 nline Backup API
3d7b0 2e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 ..** EXPERIMENTA
3d7c0 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 L.**.** This API
3d7d0 20 69 73 20 75 73 65 64 20 74 6f 20 6f 76 65 72 is used to over
3d7e0 77 72 69 74 65 20 74 68 65 20 63 6f 6e 74 65 6e write the conten
3d7f0 74 73 20 6f 66 20 6f 6e 65 20 64 61 74 61 62 61 ts of one databa
3d800 73 65 20 77 69 74 68 20 74 68 61 74 0a 2a 2a 20 se with that.**
3d810 6f 66 20 61 6e 6f 74 68 65 72 2e 20 49 74 20 69 of another. It i
3d820 73 20 75 73 65 66 75 6c 20 65 69 74 68 65 72 20 s useful either
3d830 66 6f 72 20 63 72 65 61 74 69 6e 67 20 62 61 63 for creating bac
3d840 6b 75 70 73 20 6f 66 20 64 61 74 61 62 61 73 65 kups of database
3d850 73 20 6f 72 0a 2a 2a 20 66 6f 72 20 63 6f 70 79 s or.** for copy
3d860 69 6e 67 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 ing in-memory da
3d870 74 61 62 61 73 65 73 20 74 6f 20 6f 72 20 66 72 tabases to or fr
3d880 6f 6d 20 70 65 72 73 69 73 74 65 6e 74 20 66 69 om persistent fi
3d890 6c 65 73 2e 20 0a 2a 2a 0a 2a 2a 20 53 65 65 20 les. .**.** See
3d8a0 41 6c 73 6f 3a 20 5b 55 73 69 6e 67 20 74 68 65 Also: [Using the
3d8b0 20 53 51 4c 69 74 65 20 4f 6e 6c 69 6e 65 20 42 SQLite Online B
3d8c0 61 63 6b 75 70 20 41 50 49 5d 0a 2a 2a 0a 2a 2a ackup API].**.**
3d8d0 20 45 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 Exclusive acces
3d8e0 73 20 69 73 20 72 65 71 75 69 72 65 64 20 74 6f s is required to
3d8f0 20 74 68 65 20 64 65 73 74 69 6e 61 74 69 6f 6e the destination
3d900 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 74 68 database for th
3d910 65 20 0a 2a 2a 20 64 75 72 61 74 69 6f 6e 20 6f e .** duration o
3d920 66 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 2e f the operation.
3d930 20 48 6f 77 65 76 65 72 20 74 68 65 20 73 6f 75 However the sou
3d940 72 63 65 20 64 61 74 61 62 61 73 65 20 69 73 20 rce database is
3d950 6f 6e 6c 79 0a 2a 2a 20 72 65 61 64 2d 6c 6f 63 only.** read-loc
3d960 6b 65 64 20 77 68 69 6c 65 20 69 74 20 69 73 20 ked while it is
3d970 61 63 74 75 61 6c 6c 79 20 62 65 69 6e 67 20 72 actually being r
3d980 65 61 64 2c 20 69 74 20 69 73 20 6e 6f 74 20 6c ead, it is not l
3d990 6f 63 6b 65 64 0a 2a 2a 20 63 6f 6e 74 69 6e 75 ocked.** continu
3d9a0 6f 75 73 6c 79 20 66 6f 72 20 74 68 65 20 65 6e ously for the en
3d9b0 74 69 72 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 tire operation.
3d9c0 54 68 75 73 2c 20 74 68 65 20 62 61 63 6b 75 70 Thus, the backup
3d9d0 20 6d 61 79 20 62 65 0a 2a 2a 20 70 65 72 66 6f may be.** perfo
3d9e0 72 6d 65 64 20 6f 6e 20 61 20 6c 69 76 65 20 64 rmed on a live d
3d9f0 61 74 61 62 61 73 65 20 77 69 74 68 6f 75 74 20 atabase without
3da00 70 72 65 76 65 6e 74 69 6e 67 20 6f 74 68 65 72 preventing other
3da10 20 75 73 65 72 73 20 66 72 6f 6d 0a 2a 2a 20 77 users from.** w
3da20 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20 64 61 riting to the da
3da30 74 61 62 61 73 65 20 66 6f 72 20 61 6e 20 65 78 tabase for an ex
3da40 74 65 6e 64 65 64 20 70 65 72 69 6f 64 20 6f 66 tended period of
3da50 20 74 69 6d 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 6f time..** .** To
3da60 20 70 65 72 66 6f 72 6d 20 61 20 62 61 63 6b 75 perform a backu
3da70 70 20 6f 70 65 72 61 74 69 6f 6e 3a 20 0a 2a 2a p operation: .**
3da80 20 20 20 3c 6f 6c 3e 0a 2a 2a 20 20 20 20 20 3c <ol>.** <
3da90 6c 69 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 62 61 li><b>sqlite3_ba
3daa0 63 6b 75 70 5f 69 6e 69 74 28 29 3c 2f 62 3e 20 ckup_init()</b>
3dab0 69 73 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 74 is called once t
3dac0 6f 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 o initialize the
3dad0 0a 2a 2a 20 20 20 20 20 20 20 20 20 62 61 63 6b .** back
3dae0 75 70 2c 20 0a 2a 2a 20 20 20 20 20 3c 6c 69 3e up, .** <li>
3daf0 3c 62 3e 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 <b>sqlite3_backu
3db00 70 5f 73 74 65 70 28 29 3c 2f 62 3e 20 69 73 20 p_step()</b> is
3db10 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f called one or mo
3db20 72 65 20 74 69 6d 65 73 20 74 6f 20 74 72 61 6e re times to tran
3db30 73 66 65 72 20 0a 2a 2a 20 20 20 20 20 20 20 20 sfer .**
3db40 20 74 68 65 20 64 61 74 61 20 62 65 74 77 65 65 the data betwee
3db50 6e 20 74 68 65 20 74 77 6f 20 64 61 74 61 62 61 n the two databa
3db60 73 65 73 2c 20 61 6e 64 20 66 69 6e 61 6c 6c 79 ses, and finally
3db70 0a 2a 2a 20 20 20 20 20 3c 6c 69 3e 3c 62 3e 73 .** <li><b>s
3db80 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 qlite3_backup_fi
3db90 6e 69 73 68 28 29 3c 2f 62 3e 20 69 73 20 63 61 nish()</b> is ca
3dba0 6c 6c 65 64 20 74 6f 20 72 65 6c 65 61 73 65 20 lled to release
3dbb0 61 6c 6c 20 72 65 73 6f 75 72 63 65 73 20 0a 2a all resources .*
3dbc0 2a 20 20 20 20 20 20 20 20 20 61 73 73 6f 63 69 * associ
3dbd0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 62 61 ated with the ba
3dbe0 63 6b 75 70 20 6f 70 65 72 61 74 69 6f 6e 2e 20 ckup operation.
3dbf0 0a 2a 2a 20 20 20 3c 2f 6f 6c 3e 0a 2a 2a 20 54 .** </ol>.** T
3dc00 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 65 here should be e
3dc10 78 61 63 74 6c 79 20 6f 6e 65 20 63 61 6c 6c 20 xactly one call
3dc20 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 to sqlite3_backu
3dc30 70 5f 66 69 6e 69 73 68 28 29 20 66 6f 72 20 65 p_finish() for e
3dc40 61 63 68 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 ach.** successfu
3dc50 6c 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 l call to sqlite
3dc60 33 5f 62 61 63 6b 75 70 5f 69 6e 69 74 28 29 2e 3_backup_init().
3dc70 0a 2a 2a 0a 2a 2a 20 3c 62 3e 73 71 6c 69 74 65 .**.** <b>sqlite
3dc80 33 5f 62 61 63 6b 75 70 5f 69 6e 69 74 28 29 3c 3_backup_init()<
3dc90 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 /b>.**.** The fi
3dca0 72 73 74 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 rst two argument
3dcb0 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c s passed to [sql
3dcc0 69 74 65 33 5f 62 61 63 6b 75 70 5f 69 6e 69 74 ite3_backup_init
3dcd0 28 29 5d 20 61 72 65 20 74 68 65 20 64 61 74 61 ()] are the data
3dce0 62 61 73 65 0a 2a 2a 20 68 61 6e 64 6c 65 20 61 base.** handle a
3dcf0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
3dd00 68 65 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 he destination d
3dd10 61 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20 atabase and the
3dd20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 0a 2a database name .*
3dd30 2a 20 75 73 65 64 20 74 6f 20 61 74 74 61 63 68 * used to attach
3dd40 20 74 68 65 20 64 65 73 74 69 6e 61 74 69 6f 6e the destination
3dd50 20 64 61 74 61 62 61 73 65 20 74 6f 20 74 68 65 database to the
3dd60 20 68 61 6e 64 6c 65 2e 20 54 68 65 20 64 61 74 handle. The dat
3dd70 61 62 61 73 65 20 6e 61 6d 65 0a 2a 2a 20 69 73 abase name.** is
3dd80 20 22 6d 61 69 6e 22 20 66 6f 72 20 74 68 65 20 "main" for the
3dd90 6d 61 69 6e 20 64 61 74 61 62 61 73 65 2c 20 22 main database, "
3dda0 74 65 6d 70 22 20 66 6f 72 20 74 68 65 20 74 65 temp" for the te
3ddb0 6d 70 6f 72 61 72 79 20 64 61 74 61 62 61 73 65 mporary database
3ddc0 2c 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 , or.** the name
3ddd0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61 specified as pa
3dde0 72 74 20 6f 66 20 74 68 65 20 5b 41 54 54 41 43 rt of the [ATTAC
3ddf0 48 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 66 20 H] statement if
3de00 74 68 65 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 the destination
3de10 69 73 0a 2a 2a 20 61 6e 20 61 74 74 61 63 68 65 is.** an attache
3de20 64 20 64 61 74 61 62 61 73 65 2e 20 54 68 65 20 d database. The
3de30 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 third and fourth
3de40 20 61 72 67 75 6d 65 6e 74 73 20 70 61 73 73 65 arguments passe
3de50 64 20 74 6f 20 0a 2a 2a 20 73 71 6c 69 74 65 33 d to .** sqlite3
3de60 5f 62 61 63 6b 75 70 5f 69 6e 69 74 28 29 20 69 _backup_init() i
3de70 64 65 6e 74 69 66 79 20 74 68 65 20 5b 64 61 74 dentify the [dat
3de80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
3de90 5d 0a 2a 2a 20 61 6e 64 20 64 61 74 61 62 61 73 ].** and databas
3dea0 65 20 6e 61 6d 65 20 75 73 65 64 0a 2a 2a 20 74 e name used.** t
3deb0 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 6f 75 o access the sou
3dec0 72 63 65 20 64 61 74 61 62 61 73 65 2e 20 54 68 rce database. Th
3ded0 65 20 76 61 6c 75 65 73 20 70 61 73 73 65 64 20 e values passed
3dee0 66 6f 72 20 74 68 65 20 73 6f 75 72 63 65 20 61 for the source a
3def0 6e 64 20 0a 2a 2a 20 64 65 73 74 69 6e 61 74 69 nd .** destinati
3df00 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e on [database con
3df10 6e 65 63 74 69 6f 6e 5d 20 70 61 72 61 6d 65 74 nection] paramet
3df20 65 72 73 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 ers must not be
3df30 74 68 65 20 73 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 the same..**.**
3df40 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 If an error occu
3df50 72 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 rs within sqlite
3df60 33 5f 62 61 63 6b 75 70 5f 69 6e 69 74 28 29 2c 3_backup_init(),
3df70 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 then NULL is re
3df80 74 75 72 6e 65 64 0a 2a 2a 20 61 6e 64 20 61 6e turned.** and an
3df90 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 error code and
3dfa0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 77 72 error message wr
3dfb0 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 5b itten into the [
3dfc0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
3dfd0 69 6f 6e 5d 20 0a 2a 2a 20 70 61 73 73 65 64 20 ion] .** passed
3dfe0 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 as the first arg
3dff0 75 6d 65 6e 74 2e 20 54 68 65 79 20 6d 61 79 20 ument. They may
3e000 62 65 20 72 65 74 72 69 65 76 65 64 20 75 73 69 be retrieved usi
3e010 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 ng the.** [sqlit
3e020 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b e3_errcode()], [
3e030 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 sqlite3_errmsg()
3e040 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ], and [sqlite3_
3e050 65 72 72 6d 73 67 31 36 28 29 5d 20 66 75 6e 63 errmsg16()] func
3e060 74 69 6f 6e 73 2e 0a 2a 2a 20 4f 74 68 65 72 77 tions..** Otherw
3e070 69 73 65 2c 20 69 66 20 73 75 63 63 65 73 73 66 ise, if successf
3e080 75 6c 2c 20 61 20 70 6f 69 6e 74 65 72 20 74 6f ul, a pointer to
3e090 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 an [sqlite3_bac
3e0a0 6b 75 70 5d 20 6f 62 6a 65 63 74 20 69 73 0a 2a kup] object is.*
3e0b0 2a 20 72 65 74 75 72 6e 65 64 2e 20 54 68 69 73 * returned. This
3e0c0 20 70 6f 69 6e 74 65 72 20 6d 61 79 20 62 65 20 pointer may be
3e0d0 75 73 65 64 20 77 69 74 68 20 74 68 65 20 73 71 used with the sq
3e0e0 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 lite3_backup_ste
3e0f0 70 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 p() and.** sqlit
3e100 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 e3_backup_finish
3e110 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 () functions to
3e120 70 65 72 66 6f 72 6d 20 74 68 65 20 73 70 65 63 perform the spec
3e130 69 66 69 65 64 20 62 61 63 6b 75 70 20 0a 2a 2a ified backup .**
3e140 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a operation..**.*
3e150 2a 20 3c 62 3e 73 71 6c 69 74 65 33 5f 62 61 63 * <b>sqlite3_bac
3e160 6b 75 70 5f 73 74 65 70 28 29 3c 2f 62 3e 0a 2a kup_step()</b>.*
3e170 2a 0a 2a 2a 20 46 75 6e 63 74 69 6f 6e 20 5b 73 *.** Function [s
3e180 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 qlite3_backup_st
3e190 65 70 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f ep()] is used to
3e1a0 20 63 6f 70 79 20 75 70 20 74 6f 20 6e 50 61 67 copy up to nPag
3e1b0 65 20 70 61 67 65 73 20 62 65 74 77 65 65 6e 20 e pages between
3e1c0 0a 2a 2a 20 74 68 65 20 73 6f 75 72 63 65 20 61 .** the source a
3e1d0 6e 64 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 nd destination d
3e1e0 61 74 61 62 61 73 65 73 2c 20 77 68 65 72 65 20 atabases, where
3e1f0 6e 50 61 67 65 20 69 73 20 74 68 65 20 76 61 6c nPage is the val
3e200 75 65 20 6f 66 20 74 68 65 20 0a 2a 2a 20 73 65 ue of the .** se
3e210 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 70 cond parameter p
3e220 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 assed to sqlite3
3e230 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 2e 20 _backup_step().
3e240 49 66 20 6e 50 61 67 65 20 69 73 20 61 20 6e 65 If nPage is a ne
3e250 67 61 74 69 76 65 0a 2a 2a 20 76 61 6c 75 65 2c gative.** value,
3e260 20 61 6c 6c 20 72 65 6d 61 69 6e 69 6e 67 20 73 all remaining s
3e270 6f 75 72 63 65 20 70 61 67 65 73 20 61 72 65 20 ource pages are
3e280 63 6f 70 69 65 64 2e 20 49 66 20 74 68 65 20 72 copied. If the r
3e290 65 71 75 69 72 65 64 20 70 61 67 65 73 20 61 72 equired pages ar
3e2a0 65 20 0a 2a 2a 20 73 75 63 63 65 73 66 75 6c 6c e .** succesfull
3e2b0 79 20 63 6f 70 69 65 64 2c 20 62 75 74 20 74 68 y copied, but th
3e2c0 65 72 65 20 61 72 65 20 73 74 69 6c 6c 20 6d 6f ere are still mo
3e2d0 72 65 20 70 61 67 65 73 20 74 6f 20 63 6f 70 79 re pages to copy
3e2e0 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 before the .**
3e2f0 62 61 63 6b 75 70 20 69 73 20 63 6f 6d 70 6c 65 backup is comple
3e300 74 65 2c 20 69 74 20 72 65 74 75 72 6e 73 20 5b te, it returns [
3e310 53 51 4c 49 54 45 5f 4f 4b 5d 2e 20 49 66 20 6e SQLITE_OK]. If n
3e320 6f 20 65 72 72 6f 72 20 6f 63 63 75 72 65 64 20 o error occured
3e330 61 6e 64 20 74 68 65 72 65 20 0a 2a 2a 20 61 72 and there .** ar
3e340 65 20 6e 6f 20 6d 6f 72 65 20 70 61 67 65 73 20 e no more pages
3e350 74 6f 20 63 6f 70 79 2c 20 74 68 65 6e 20 5b 53 to copy, then [S
3e360 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 69 73 20 72 QLITE_DONE] is r
3e370 65 74 75 72 6e 65 64 2e 20 49 66 20 61 6e 20 65 eturned. If an e
3e380 72 72 6f 72 20 0a 2a 2a 20 6f 63 63 75 72 73 2c rror .** occurs,
3e390 20 74 68 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 then an SQLite
3e3a0 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 error code is re
3e3b0 74 75 72 6e 65 64 2e 20 41 73 20 77 65 6c 6c 20 turned. As well
3e3c0 61 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 as [SQLITE_OK] a
3e3d0 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f nd.** [SQLITE_DO
3e3e0 4e 45 5d 2c 20 61 20 63 61 6c 6c 20 74 6f 20 73 NE], a call to s
3e3f0 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 qlite3_backup_st
3e400 65 70 28 29 20 6d 61 79 20 72 65 74 75 72 6e 20 ep() may return
3e410 5b 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 [SQLITE_READONLY
3e420 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f ],.** [SQLITE_NO
3e430 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 MEM], [SQLITE_BU
3e440 53 59 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 SY], [SQLITE_LOC
3e450 4b 45 44 5d 2c 20 6f 72 20 61 6e 0a 2a 2a 20 5b KED], or an.** [
3e460 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 SQLITE_IOERR_ACC
3e470 45 53 53 20 7c 20 53 51 4c 49 54 45 5f 49 4f 45 ESS | SQLITE_IOE
3e480 52 52 5f 58 58 58 5d 20 65 78 74 65 6e 64 65 64 RR_XXX] extended
3e490 20 65 72 72 6f 72 20 63 6f 64 65 2e 0a 2a 2a 0a error code..**.
3e4a0 2a 2a 20 41 73 20 77 65 6c 6c 20 61 73 20 74 68 ** As well as th
3e4b0 65 20 63 61 73 65 20 77 68 65 72 65 20 74 68 65 e case where the
3e4c0 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 destination dat
3e4d0 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 6f abase file was o
3e4e0 70 65 6e 65 64 20 66 6f 72 0a 2a 2a 20 72 65 61 pened for.** rea
3e4f0 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2c 20 73 d-only access, s
3e500 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 qlite3_backup_st
3e510 65 70 28 29 20 6d 61 79 20 72 65 74 75 72 6e 20 ep() may return
3e520 5b 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 [SQLITE_READONLY
3e530 5d 20 69 66 0a 2a 2a 20 74 68 65 20 64 65 73 74 ] if.** the dest
3e540 69 6e 61 74 69 6f 6e 20 69 73 20 61 6e 20 69 6e ination is an in
3e550 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 -memory database
3e560 20 77 69 74 68 20 61 20 64 69 66 66 65 72 65 6e with a differen
3e570 74 20 70 61 67 65 20 73 69 7a 65 0a 2a 2a 20 66 t page size.** f
3e580 72 6f 6d 20 74 68 65 20 73 6f 75 72 63 65 20 64 rom the source d
3e590 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 49 atabase..**.** I
3e5a0 66 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 f sqlite3_backup
3e5b0 5f 73 74 65 70 28 29 20 63 61 6e 6e 6f 74 20 6f _step() cannot o
3e5c0 62 74 61 69 6e 20 61 20 72 65 71 75 69 72 65 64 btain a required
3e5d0 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 6c 6f 63 file-system loc
3e5e0 6b 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 5b k, then.** the [
3e5f0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e sqlite3_busy_han
3e600 64 6c 65 72 20 7c 20 62 75 73 79 2d 68 61 6e 64 dler | busy-hand
3e610 6c 65 72 20 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2a ler function].**
3e620 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 66 20 is invoked (if
3e630 6f 6e 65 20 69 73 20 73 70 65 63 69 66 69 65 64 one is specified
3e640 29 2e 20 49 66 20 74 68 65 20 0a 2a 2a 20 62 75 ). If the .** bu
3e650 73 79 2d 68 61 6e 64 6c 65 72 20 72 65 74 75 72 sy-handler retur
3e660 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 62 65 66 6f ns non-zero befo
3e670 72 65 20 74 68 65 20 6c 6f 63 6b 20 69 73 20 61 re the lock is a
3e680 76 61 69 6c 61 62 6c 65 2c 20 74 68 65 6e 20 0a vailable, then .
3e690 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d ** [SQLITE_BUSY]
3e6a0 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 is returned to
3e6b0 74 68 65 20 63 61 6c 6c 65 72 2e 20 49 6e 20 74 the caller. In t
3e6c0 68 69 73 20 63 61 73 65 20 74 68 65 20 63 61 6c his case the cal
3e6d0 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f l to.** sqlite3_
3e6e0 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 63 61 backup_step() ca
3e6f0 6e 20 62 65 20 72 65 74 72 69 65 64 20 6c 61 74 n be retried lat
3e700 65 72 2e 20 49 66 20 74 68 65 20 73 6f 75 72 63 er. If the sourc
3e710 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 e.** [database c
3e720 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 73 onnection].** is
3e730 20 62 65 69 6e 67 20 75 73 65 64 20 74 6f 20 77 being used to w
3e740 72 69 74 65 20 74 6f 20 74 68 65 20 73 6f 75 72 rite to the sour
3e750 63 65 20 64 61 74 61 62 61 73 65 20 77 68 65 6e ce database when
3e760 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f sqlite3_backup_
3e770 73 74 65 70 28 29 0a 2a 2a 20 69 73 20 63 61 6c step().** is cal
3e780 6c 65 64 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 led, then [SQLIT
3e790 45 5f 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 E_LOCKED] is ret
3e7a0 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c urned immediatel
3e7b0 79 2e 20 41 67 61 69 6e 2c 20 69 6e 20 74 68 69 y. Again, in thi
3e7c0 73 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 63 61 s.** case the ca
3e7d0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 ll to sqlite3_ba
3e7e0 63 6b 75 70 5f 73 74 65 70 28 29 20 63 61 6e 20 ckup_step() can
3e7f0 62 65 20 72 65 74 72 69 65 64 20 6c 61 74 65 72 be retried later
3e800 20 6f 6e 2e 20 49 66 0a 2a 2a 20 5b 53 51 4c 49 on. If.** [SQLI
3e810 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 TE_IOERR_ACCESS
3e820 7c 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 58 | SQLITE_IOERR_X
3e830 58 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d XX], [SQLITE_NOM
3e840 45 4d 5d 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 EM], or.** [SQLI
3e850 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 20 69 73 20 TE_READONLY] is
3e860 72 65 74 75 72 6e 65 64 2c 20 74 68 65 6e 20 0a returned, then .
3e870 2a 2a 20 74 68 65 72 65 20 69 73 20 6e 6f 20 70 ** there is no p
3e880 6f 69 6e 74 20 69 6e 20 72 65 74 72 79 69 6e 67 oint in retrying
3e890 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c the call to sql
3e8a0 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 ite3_backup_step
3e8b0 28 29 2e 20 54 68 65 73 65 20 0a 2a 2a 20 65 72 (). These .** er
3e8c0 72 6f 72 73 20 61 72 65 20 63 6f 6e 73 69 64 65 rors are conside
3e8d0 72 65 64 20 66 61 74 61 6c 2e 20 41 74 20 74 68 red fatal. At th
3e8e0 69 73 20 70 6f 69 6e 74 20 74 68 65 20 61 70 70 is point the app
3e8f0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 61 63 lication must ac
3e900 63 65 70 74 20 0a 2a 2a 20 74 68 61 74 20 74 68 cept .** that th
3e910 65 20 62 61 63 6b 75 70 20 6f 70 65 72 61 74 69 e backup operati
3e920 6f 6e 20 68 61 73 20 66 61 69 6c 65 64 20 61 6e on has failed an
3e930 64 20 70 61 73 73 20 74 68 65 20 62 61 63 6b 75 d pass the backu
3e940 70 20 6f 70 65 72 61 74 69 6f 6e 20 68 61 6e 64 p operation hand
3e950 6c 65 20 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 le .** to the sq
3e960 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e lite3_backup_fin
3e970 69 73 68 28 29 20 74 6f 20 72 65 6c 65 61 73 65 ish() to release
3e980 20 61 73 73 6f 63 69 61 74 65 64 20 72 65 73 6f associated reso
3e990 75 72 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 46 6f 6c urces..**.** Fol
3e9a0 6c 6f 77 69 6e 67 20 74 68 65 20 66 69 72 73 74 lowing the first
3e9b0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
3e9c0 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 2c 20 _backup_step(),
3e9d0 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 an exclusive loc
3e9e0 6b 20 69 73 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 k is.** obtained
3e9f0 20 6f 6e 20 74 68 65 20 64 65 73 74 69 6e 61 74 on the destinat
3ea00 69 6f 6e 20 66 69 6c 65 2e 20 49 74 20 69 73 20 ion file. It is
3ea10 6e 6f 74 20 72 65 6c 65 61 73 65 64 20 75 6e 74 not released unt
3ea20 69 6c 20 65 69 74 68 65 72 20 0a 2a 2a 20 73 71 il either .** sq
3ea30 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e lite3_backup_fin
3ea40 69 73 68 28 29 20 69 73 20 63 61 6c 6c 65 64 20 ish() is called
3ea50 6f 72 20 74 68 65 20 62 61 63 6b 75 70 20 6f 70 or the backup op
3ea60 65 72 61 74 69 6f 6e 20 69 73 20 63 6f 6d 70 6c eration is compl
3ea70 65 74 65 20 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 ete .** and sqli
3ea80 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 te3_backup_step(
3ea90 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 ) returns [SQLIT
3eaa0 45 5f 44 4f 4e 45 5d 2e 20 41 64 64 69 74 69 6f E_DONE]. Additio
3eab0 6e 61 6c 6c 79 2c 20 65 61 63 68 20 74 69 6d 65 nally, each time
3eac0 20 0a 2a 2a 20 61 20 63 61 6c 6c 20 74 6f 20 73 .** a call to s
3ead0 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 qlite3_backup_st
3eae0 65 70 28 29 20 69 73 20 6d 61 64 65 20 61 20 5b ep() is made a [
3eaf0 73 68 61 72 65 64 20 6c 6f 63 6b 5d 20 69 73 20 shared lock] is
3eb00 6f 62 74 61 69 6e 65 64 20 6f 6e 0a 2a 2a 20 74 obtained on.** t
3eb10 68 65 20 73 6f 75 72 63 65 20 64 61 74 61 62 61 he source databa
3eb20 73 65 20 66 69 6c 65 2e 20 54 68 69 73 20 6c 6f se file. This lo
3eb30 63 6b 20 69 73 20 72 65 6c 65 61 73 65 64 20 62 ck is released b
3eb40 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 73 71 6c efore the.** sql
3eb50 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 ite3_backup_step
3eb60 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e () call returns.
3eb70 20 42 65 63 61 75 73 65 20 74 68 65 20 73 6f 75 Because the sou
3eb80 72 63 65 20 64 61 74 61 62 61 73 65 20 69 73 20 rce database is
3eb90 6e 6f 74 0a 2a 2a 20 6c 6f 63 6b 65 64 20 62 65 not.** locked be
3eba0 74 77 65 65 6e 20 63 61 6c 6c 73 20 74 6f 20 73 tween calls to s
3ebb0 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 qlite3_backup_st
3ebc0 65 70 28 29 2c 20 69 74 20 6d 61 79 20 62 65 20 ep(), it may be
3ebd0 6d 6f 64 69 66 69 65 64 20 6d 69 64 2d 77 61 79 modified mid-way
3ebe0 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 .** through the
3ebf0 62 61 63 6b 75 70 20 70 72 6f 63 65 64 75 72 65 backup procedure
3ec00 2e 20 49 66 20 74 68 65 20 73 6f 75 72 63 65 20 . If the source
3ec10 64 61 74 61 62 61 73 65 20 69 73 20 6d 6f 64 69 database is modi
3ec20 66 69 65 64 20 62 79 20 61 6e 0a 2a 2a 20 65 78 fied by an.** ex
3ec30 74 65 72 6e 61 6c 20 70 72 6f 63 65 73 73 20 6f ternal process o
3ec40 72 20 76 69 61 20 61 20 64 61 74 61 62 61 73 65 r via a database
3ec50 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 74 68 65 connection othe
3ec60 72 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 62 r than the one b
3ec70 65 69 6e 67 0a 2a 2a 20 75 73 65 64 20 62 79 20 eing.** used by
3ec80 74 68 65 20 62 61 63 6b 75 70 20 6f 70 65 72 61 the backup opera
3ec90 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 62 tion, then the b
3eca0 61 63 6b 75 70 20 77 69 6c 6c 20 62 65 20 74 72 ackup will be tr
3ecb0 61 6e 73 70 61 72 65 6e 74 6c 79 0a 2a 2a 20 72 ansparently.** r
3ecc0 65 73 74 61 72 74 65 64 20 62 79 20 74 68 65 20 estarted by the
3ecd0 6e 65 78 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c next call to sql
3ece0 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 ite3_backup_step
3ecf0 28 29 2e 20 49 66 20 74 68 65 20 73 6f 75 72 63 (). If the sourc
3ed00 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 e .** database i
3ed10 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68 s modified by th
3ed20 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 e using the same
3ed30 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
3ed40 74 69 6f 6e 20 61 73 20 69 73 20 75 73 65 64 0a tion as is used.
3ed50 2a 2a 20 62 79 20 74 68 65 20 62 61 63 6b 75 70 ** by the backup
3ed60 20 6f 70 65 72 61 74 69 6f 6e 2c 20 74 68 65 6e operation, then
3ed70 20 74 68 65 20 62 61 63 6b 75 70 20 64 61 74 61 the backup data
3ed80 62 61 73 65 20 69 73 20 74 72 61 6e 73 70 61 72 base is transpar
3ed90 65 6e 74 6c 79 20 0a 2a 2a 20 75 70 64 61 74 65 ently .** update
3eda0 64 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 d at the same ti
3edb0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 73 71 6c me..**.** <b>sql
3edc0 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 ite3_backup_fini
3edd0 73 68 28 29 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 4f sh()</b>.**.** O
3ede0 6e 63 65 20 73 71 6c 69 74 65 33 5f 62 61 63 6b nce sqlite3_back
3edf0 75 70 5f 73 74 65 70 28 29 20 68 61 73 20 72 65 up_step() has re
3ee00 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 turned [SQLITE_D
3ee10 4f 4e 45 5d 2c 20 6f 72 20 77 68 65 6e 20 74 68 ONE], or when th
3ee20 65 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f e .** applicatio
3ee30 6e 20 77 69 73 68 65 73 20 74 6f 20 61 62 61 6e n wishes to aban
3ee40 64 6f 6e 20 74 68 65 20 62 61 63 6b 75 70 20 6f don the backup o
3ee50 70 65 72 61 74 69 6f 6e 2c 20 74 68 65 20 5b 73 peration, the [s
3ee60 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 0a 2a qlite3_backup].*
3ee70 2a 20 6f 62 6a 65 63 74 20 73 68 6f 75 6c 64 20 * object should
3ee80 62 65 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c be passed to sql
3ee90 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 ite3_backup_fini
3eea0 73 68 28 29 2e 20 54 68 69 73 20 72 65 6c 65 61 sh(). This relea
3eeb0 73 65 73 20 61 6c 6c 0a 2a 2a 20 72 65 73 6f 75 ses all.** resou
3eec0 72 63 65 73 20 61 73 73 6f 63 69 61 74 65 64 20 rces associated
3eed0 77 69 74 68 20 74 68 65 20 62 61 63 6b 75 70 20 with the backup
3eee0 6f 70 65 72 61 74 69 6f 6e 2e 20 49 66 20 73 71 operation. If sq
3eef0 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 lite3_backup_ste
3ef00 70 28 29 0a 2a 2a 20 68 61 73 20 6e 6f 74 20 79 p().** has not y
3ef10 65 74 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c et returned [SQL
3ef20 49 54 45 5f 44 4f 4e 45 5d 2c 20 74 68 65 6e 20 ITE_DONE], then
3ef30 61 6e 79 20 61 63 74 69 76 65 20 77 72 69 74 65 any active write
3ef40 2d 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 6e 20 -transaction on
3ef50 74 68 65 0a 2a 2a 20 64 65 73 74 69 6e 61 74 69 the.** destinati
3ef60 6f 6e 20 64 61 74 61 62 61 73 65 20 69 73 20 72 on database is r
3ef70 6f 6c 6c 65 64 20 62 61 63 6b 2e 20 54 68 65 20 olled back. The
3ef80 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d [sqlite3_backup]
3ef90 20 6f 62 6a 65 63 74 20 69 73 20 69 6e 76 61 6c object is inval
3efa0 69 64 0a 2a 2a 20 61 6e 64 20 6d 61 79 20 6e 6f id.** and may no
3efb0 74 20 62 65 20 75 73 65 64 20 66 6f 6c 6c 6f 77 t be used follow
3efc0 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 ing a call to sq
3efd0 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e lite3_backup_fin
3efe0 69 73 68 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ish()..**.** The
3eff0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
3f000 62 79 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 by sqlite3_backu
3f010 70 5f 66 69 6e 69 73 68 20 69 73 20 5b 53 51 4c p_finish is [SQL
3f020 49 54 45 5f 4f 4b 5d 20 69 66 20 6e 6f 20 65 72 ITE_OK] if no er
3f030 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 72 65 64 2c ror.** occurred,
3f040 20 72 65 67 61 72 64 6c 65 73 73 20 6f 72 20 77 regardless or w
3f050 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 71 hether or not sq
3f060 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 lite3_backup_ste
3f070 70 28 29 20 77 61 73 20 63 61 6c 6c 65 64 0a 2a p() was called.*
3f080 2a 20 61 20 73 75 66 66 69 63 69 65 6e 74 20 6e * a sufficient n
3f090 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 umber of times t
3f0a0 6f 20 63 6f 6d 70 6c 65 74 65 20 74 68 65 20 62 o complete the b
3f0b0 61 63 6b 75 70 20 6f 70 65 72 61 74 69 6f 6e 2e ackup operation.
3f0c0 20 4f 72 2c 20 69 66 0a 2a 2a 20 61 6e 20 6f 75 Or, if.** an ou
3f0d0 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 t-of-memory cond
3f0e0 69 74 69 6f 6e 20 6f 72 20 49 4f 20 65 72 72 6f ition or IO erro
3f0f0 72 20 6f 63 63 75 72 65 64 20 64 75 72 69 6e 67 r occured during
3f100 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 a call to.** sq
3f110 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 lite3_backup_ste
3f120 70 28 29 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 p() then [SQLITE
3f130 5f 4e 4f 4d 45 4d 5d 20 6f 72 20 61 6e 0a 2a 2a _NOMEM] or an.**
3f140 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 [SQLITE_IOERR_A
3f150 43 43 45 53 53 20 7c 20 53 51 4c 49 54 45 5f 49 CCESS | SQLITE_I
3f160 4f 45 52 52 5f 58 58 58 5d 20 65 72 72 6f 72 20 OERR_XXX] error
3f170 63 6f 64 65 0a 2a 2a 20 69 73 20 72 65 74 75 72 code.** is retur
3f180 6e 65 64 2e 20 49 6e 20 74 68 69 73 20 63 61 73 ned. In this cas
3f190 65 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 e the error code
3f1a0 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 and an error me
3f1b0 73 73 61 67 65 20 61 72 65 0a 2a 2a 20 77 72 69 ssage are.** wri
3f1c0 74 74 65 6e 20 74 6f 20 74 68 65 20 64 65 73 74 tten to the dest
3f1d0 69 6e 61 74 69 6f 6e 20 5b 64 61 74 61 62 61 73 ination [databas
3f1e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a e connection]..*
3f1f0 2a 0a 2a 2a 20 41 20 72 65 74 75 72 6e 20 6f 66 *.** A return of
3f200 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f [SQLITE_BUSY] o
3f210 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 r [SQLITE_LOCKED
3f220 5d 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 62 ] from sqlite3_b
3f230 61 63 6b 75 70 5f 73 74 65 70 28 29 20 69 73 0a ackup_step() is.
3f240 2a 2a 20 6e 6f 74 20 61 20 70 65 72 6d 61 6e 65 ** not a permane
3f250 6e 74 20 65 72 72 6f 72 20 61 6e 64 20 64 6f 65 nt error and doe
3f260 73 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65 s not affect the
3f270 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 return value of
3f280 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 6b .** sqlite3_back
3f290 75 70 5f 66 69 6e 69 73 68 28 29 2e 0a 2a 2a 0a up_finish()..**.
3f2a0 2a 2a 20 3c 62 3e 73 71 6c 69 74 65 33 5f 62 61 ** <b>sqlite3_ba
3f2b0 63 6b 75 70 5f 72 65 6d 61 69 6e 69 6e 67 28 29 ckup_remaining()
3f2c0 2c 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 , sqlite3_backup
3f2d0 5f 70 61 67 65 63 6f 75 6e 74 28 29 3c 2f 62 3e _pagecount()</b>
3f2e0 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 63 61 6c 6c .**.** Each call
3f2f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b to sqlite3_back
3f300 75 70 5f 73 74 65 70 28 29 20 73 65 74 73 20 74 up_step() sets t
3f310 77 6f 20 76 61 6c 75 65 73 20 73 74 6f 72 65 64 wo values stored
3f320 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 62 internally.** b
3f330 79 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 62 61 y an [sqlite3_ba
3f340 63 6b 75 70 5d 20 6f 62 6a 65 63 74 2e 20 54 68 ckup] object. Th
3f350 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 e number of page
3f360 73 20 73 74 69 6c 6c 20 74 6f 20 62 65 20 62 61 s still to be ba
3f370 63 6b 65 64 0a 2a 2a 20 75 70 2c 20 77 68 69 63 cked.** up, whic
3f380 68 20 6d 61 79 20 62 65 20 71 75 65 72 69 65 64 h may be queried
3f390 20 62 79 20 73 71 6c 69 74 65 33 5f 62 61 63 6b by sqlite3_back
3f3a0 75 70 5f 72 65 6d 61 69 6e 69 6e 67 28 29 2c 20 up_remaining(),
3f3b0 61 6e 64 20 74 68 65 20 74 6f 74 61 6c 0a 2a 2a and the total.**
3f3c0 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 number of pages
3f3d0 20 69 6e 20 74 68 65 20 73 6f 75 72 63 65 20 64 in the source d
3f3e0 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 77 68 atabase file, wh
3f3f0 69 63 68 20 6d 61 79 20 62 65 20 71 75 65 72 69 ich may be queri
3f400 65 64 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 ed by.** sqlite3
3f410 5f 62 61 63 6b 75 70 5f 70 61 67 65 63 6f 75 6e _backup_pagecoun
3f420 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 t()..**.** The v
3f430 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 alues returned b
3f440 79 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e y these function
3f450 73 20 61 72 65 20 6f 6e 6c 79 20 75 70 64 61 74 s are only updat
3f460 65 64 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 ed by.** sqlite3
3f470 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 2e 20 _backup_step().
3f480 49 66 20 74 68 65 20 73 6f 75 72 63 65 20 64 61 If the source da
3f490 74 61 62 61 73 65 20 69 73 20 6d 6f 64 69 66 69 tabase is modifi
3f4a0 65 64 20 64 75 72 69 6e 67 20 61 20 62 61 63 6b ed during a back
3f4b0 75 70 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 2c up.** operation,
3f4c0 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 73 then the values
3f4d0 20 61 72 65 20 6e 6f 74 20 75 70 64 61 74 65 64 are not updated
3f4e0 20 74 6f 20 61 63 63 6f 75 6e 74 20 66 6f 72 20 to account for
3f4f0 61 6e 79 20 65 78 74 72 61 0a 2a 2a 20 70 61 67 any extra.** pag
3f500 65 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 es that need to
3f510 62 65 20 75 70 64 61 74 65 64 20 6f 72 20 74 68 be updated or th
3f520 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 6f e size of the so
3f530 75 72 63 65 20 64 61 74 61 62 61 73 65 20 66 69 urce database fi
3f540 6c 65 0a 2a 2a 20 63 68 61 6e 67 69 6e 67 2e 0a le.** changing..
3f550 2a 2a 0a 2a 2a 20 3c 62 3e 43 6f 6e 63 75 72 72 **.** <b>Concurr
3f560 65 6e 74 20 55 73 61 67 65 20 6f 66 20 44 61 74 ent Usage of Dat
3f570 61 62 61 73 65 20 48 61 6e 64 6c 65 73 3c 2f 62 abase Handles</b
3f580 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 6f 75 72 >.**.** The sour
3f590 63 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ce [database con
3f5a0 6e 65 63 74 69 6f 6e 5d 20 6d 61 79 20 62 65 20 nection] may be
3f5b0 75 73 65 64 20 62 79 20 74 68 65 20 61 70 70 6c used by the appl
3f5c0 69 63 61 74 69 6f 6e 20 66 6f 72 20 6f 74 68 65 ication for othe
3f5d0 72 0a 2a 2a 20 70 75 72 70 6f 73 65 73 20 77 68 r.** purposes wh
3f5e0 69 6c 65 20 61 20 62 61 63 6b 75 70 20 6f 70 65 ile a backup ope
3f5f0 72 61 74 69 6f 6e 20 69 73 20 75 6e 64 65 72 77 ration is underw
3f600 61 79 20 6f 72 20 62 65 69 6e 67 20 69 6e 69 74 ay or being init
3f610 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 49 66 20 53 ialized..** If S
3f620 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
3f630 64 20 61 6e 64 20 63 6f 6e 66 69 67 75 72 65 64 d and configured
3f640 20 74 6f 20 73 75 70 70 6f 72 74 20 74 68 72 65 to support thre
3f650 61 64 73 61 66 65 20 64 61 74 61 62 61 73 65 0a adsafe database.
3f660 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2c 20 ** connections,
3f670 74 68 65 6e 20 74 68 65 20 73 6f 75 72 63 65 20 then the source
3f680 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
3f690 69 6f 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20 ion may be used
3f6a0 63 6f 6e 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 concurrently.**
3f6b0 66 72 6f 6d 20 77 69 74 68 69 6e 20 6f 74 68 65 from within othe
3f6c0 72 20 74 68 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a r threads..**.**
3f6d0 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 61 70 However, the ap
3f6e0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 67 plication must g
3f6f0 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 uarantee that th
3f700 65 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 e destination da
3f710 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 tabase.** connec
3f720 74 69 6f 6e 20 68 61 6e 64 6c 65 20 69 73 20 6e tion handle is n
3f730 6f 74 20 70 61 73 73 65 64 20 74 6f 20 61 6e 79 ot passed to any
3f740 20 6f 74 68 65 72 20 41 50 49 20 28 62 79 20 61 other API (by a
3f750 6e 79 20 74 68 72 65 61 64 29 20 61 66 74 65 72 ny thread) after
3f760 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 .** sqlite3_bac
3f770 6b 75 70 5f 69 6e 69 74 28 29 20 69 73 20 63 61 kup_init() is ca
3f780 6c 6c 65 64 20 61 6e 64 20 62 65 66 6f 72 65 20 lled and before
3f790 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e the correspondin
3f7a0 67 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c g call to.** sql
3f7b0 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 ite3_backup_fini
3f7c0 73 68 28 29 2e 20 55 6e 66 6f 72 74 75 6e 61 74 sh(). Unfortunat
3f7d0 65 6c 79 20 53 51 4c 69 74 65 20 64 6f 65 73 20 ely SQLite does
3f7e0 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 63 68 not currently ch
3f7f0 65 63 6b 0a 2a 2a 20 66 6f 72 20 74 68 69 73 2c eck.** for this,
3f800 20 69 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 if the applicat
3f810 69 6f 6e 20 64 6f 65 73 20 75 73 65 20 74 68 65 ion does use the
3f820 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 5b 64 61 destination [da
3f830 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
3f840 6e 5d 0a 2a 2a 20 66 6f 72 20 73 6f 6d 65 20 6f n].** for some o
3f850 74 68 65 72 20 70 75 72 70 6f 73 65 20 64 75 72 ther purpose dur
3f860 69 6e 67 20 61 20 62 61 63 6b 75 70 20 6f 70 65 ing a backup ope
3f870 72 61 74 69 6f 6e 2c 20 74 68 69 6e 67 73 20 6d ration, things m
3f880 61 79 20 61 70 70 65 61 72 20 74 6f 0a 2a 2a 20 ay appear to.**
3f890 77 6f 72 6b 20 63 6f 72 72 65 63 74 6c 79 20 62 work correctly b
3f8a0 75 74 20 69 6e 20 66 61 63 74 20 62 65 20 73 75 ut in fact be su
3f8b0 62 74 6c 79 20 6d 61 6c 66 75 6e 63 74 69 6f 6e btly malfunction
3f8c0 69 6e 67 2e 20 20 55 73 65 20 6f 66 20 74 68 65 ing. Use of the
3f8d0 0a 2a 2a 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 .** destination
3f8e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
3f8f0 69 6f 6e 20 77 68 69 6c 65 20 61 20 62 61 63 6b ion while a back
3f900 75 70 20 69 73 20 69 6e 20 70 72 6f 67 72 65 73 up is in progres
3f910 73 20 6d 69 67 68 74 0a 2a 2a 20 61 6c 73 6f 20 s might.** also
3f920 63 61 75 73 65 20 61 20 6d 75 74 65 78 20 64 65 cause a mutex de
3f930 61 64 6c 6f 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 75 adlock..**.** Fu
3f940 72 74 68 65 72 6d 6f 72 65 2c 20 69 66 20 72 75 rthermore, if ru
3f950 6e 6e 69 6e 67 20 69 6e 20 5b 73 68 61 72 65 64 nning in [shared
3f960 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 74 68 cache mode], th
3f970 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 e application mu
3f980 73 74 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 20 st.** guarantee
3f990 74 68 61 74 20 74 68 65 20 73 68 61 72 65 64 20 that the shared
3f9a0 63 61 63 68 65 20 75 73 65 64 20 62 79 20 74 68 cache used by th
3f9b0 65 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 e destination da
3f9c0 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 tabase.** is not
3f9d0 20 61 63 63 65 73 73 65 64 20 77 68 69 6c 65 20 accessed while
3f9e0 74 68 65 20 62 61 63 6b 75 70 20 69 73 20 72 75 the backup is ru
3f9f0 6e 6e 69 6e 67 2e 20 49 6e 20 70 72 61 63 74 69 nning. In practi
3fa00 63 65 20 74 68 69 73 20 6d 65 61 6e 73 0a 2a 2a ce this means.**
3fa10 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 that the applic
3fa20 61 74 69 6f 6e 20 6d 75 73 74 20 67 75 61 72 61 ation must guara
3fa30 6e 74 65 65 20 74 68 61 74 20 74 68 65 20 66 69 ntee that the fi
3fa40 6c 65 2d 73 79 73 74 65 6d 20 66 69 6c 65 20 62 le-system file b
3fa50 65 69 6e 67 20 0a 2a 2a 20 62 61 63 6b 65 64 20 eing .** backed
3fa60 75 70 20 74 6f 20 69 73 20 6e 6f 74 20 61 63 63 up to is not acc
3fa70 65 73 73 65 64 20 62 79 20 61 6e 79 20 63 6f 6e essed by any con
3fa80 6e 65 63 74 69 6f 6e 20 77 69 74 68 69 6e 20 74 nection within t
3fa90 68 65 20 70 72 6f 63 65 73 73 2c 0a 2a 2a 20 6e he process,.** n
3faa0 6f 74 20 6a 75 73 74 20 74 68 65 20 73 70 65 63 ot just the spec
3fab0 69 66 69 63 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 ific connection
3fac0 74 68 61 74 20 77 61 73 20 70 61 73 73 65 64 20 that was passed
3fad0 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 to sqlite3_backu
3fae0 70 5f 69 6e 69 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 p_init()..**.**
3faf0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 The [sqlite3_bac
3fb00 6b 75 70 5d 20 6f 62 6a 65 63 74 20 69 74 73 65 kup] object itse
3fb10 6c 66 20 69 73 20 70 61 72 74 69 61 6c 6c 79 20 lf is partially
3fb20 74 68 72 65 61 64 73 61 66 65 2e 20 4d 75 6c 74 threadsafe. Mult
3fb30 69 70 6c 65 20 0a 2a 2a 20 74 68 72 65 61 64 73 iple .** threads
3fb40 20 6d 61 79 20 73 61 66 65 6c 79 20 6d 61 6b 65 may safely make
3fb50 20 6d 75 6c 74 69 70 6c 65 20 63 6f 6e 63 75 72 multiple concur
3fb60 72 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 73 71 rent calls to sq
3fb70 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 lite3_backup_ste
3fb80 70 28 29 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c p()..** However,
3fb90 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 61 63 the sqlite3_bac
3fba0 6b 75 70 5f 72 65 6d 61 69 6e 69 6e 67 28 29 20 kup_remaining()
3fbb0 61 6e 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b and sqlite3_back
3fbc0 75 70 5f 70 61 67 65 63 6f 75 6e 74 28 29 0a 2a up_pagecount().*
3fbd0 2a 20 41 50 49 73 20 61 72 65 20 6e 6f 74 20 73 * APIs are not s
3fbe0 74 72 69 63 74 6c 79 20 73 70 65 61 6b 69 6e 67 trictly speaking
3fbf0 20 74 68 72 65 61 64 73 61 66 65 2e 20 49 66 20 threadsafe. If
3fc00 74 68 65 79 20 61 72 65 20 69 6e 76 6f 6b 65 64 they are invoked
3fc10 20 61 74 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 at the.** same
3fc20 74 69 6d 65 20 61 73 20 61 6e 6f 74 68 65 72 20 time as another
3fc30 74 68 72 65 61 64 20 69 73 20 69 6e 76 6f 6b 69 thread is invoki
3fc40 6e 67 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 ng sqlite3_backu
3fc50 70 5f 73 74 65 70 28 29 20 69 74 20 69 73 0a 2a p_step() it is.*
3fc60 2a 20 70 6f 73 73 69 62 6c 65 20 74 68 61 74 20 * possible that
3fc70 74 68 65 79 20 72 65 74 75 72 6e 20 69 6e 76 61 they return inva
3fc80 6c 69 64 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 lid values..*/.S
3fc90 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 QLITE_API sqlite
3fca0 33 5f 62 61 63 6b 75 70 20 2a 73 71 6c 69 74 65 3_backup *sqlite
3fcb0 33 5f 62 61 63 6b 75 70 5f 69 6e 69 74 28 0a 20 3_backup_init(.
3fcc0 20 73 71 6c 69 74 65 33 20 2a 70 44 65 73 74 2c sqlite3 *pDest,
3fcd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3fce0 20 20 20 20 20 20 20 20 2f 2a 20 44 65 73 74 69 /* Desti
3fcf0 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 73 65 20 nation database
3fd00 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
3fd10 74 20 63 68 61 72 20 2a 7a 44 65 73 74 4e 61 6d t char *zDestNam
3fd20 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 e,
3fd30 20 20 20 2f 2a 20 44 65 73 74 69 6e 61 74 69 6f /* Destinatio
3fd40 6e 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 n database name
3fd50 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 70 53 */. sqlite3 *pS
3fd60 6f 75 72 63 65 2c 20 20 20 20 20 20 20 20 20 20 ource,
3fd70 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 /* S
3fd80 6f 75 72 63 65 20 64 61 74 61 62 61 73 65 20 68 ource database h
3fd90 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
3fda0 20 63 68 61 72 20 2a 7a 53 6f 75 72 63 65 4e 61 char *zSourceNa
3fdb0 6d 65 20 20 20 20 20 20 20 20 20 20 20 20 20 20 me
3fdc0 20 20 2f 2a 20 53 6f 75 72 63 65 20 64 61 74 61 /* Source data
3fdd0 62 61 73 65 20 6e 61 6d 65 20 2a 2f 0a 29 3b 0a base name */.);.
3fde0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
3fdf0 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 qlite3_backup_st
3fe00 65 70 28 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 ep(sqlite3_backu
3fe10 70 20 2a 70 2c 20 69 6e 74 20 6e 50 61 67 65 29 p *p, int nPage)
3fe20 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
3fe30 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f sqlite3_backup_
3fe40 66 69 6e 69 73 68 28 73 71 6c 69 74 65 33 5f 62 finish(sqlite3_b
3fe50 61 63 6b 75 70 20 2a 70 29 3b 0a 53 51 4c 49 54 ackup *p);.SQLIT
3fe60 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
3fe70 33 5f 62 61 63 6b 75 70 5f 72 65 6d 61 69 6e 69 3_backup_remaini
3fe80 6e 67 28 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 ng(sqlite3_backu
3fe90 70 20 2a 70 29 3b 0a 53 51 4c 49 54 45 5f 41 50 p *p);.SQLITE_AP
3fea0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 61 I int sqlite3_ba
3feb0 63 6b 75 70 5f 70 61 67 65 63 6f 75 6e 74 28 73 ckup_pagecount(s
3fec0 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 2a 70 qlite3_backup *p
3fed0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
3fee0 45 46 3a 20 55 6e 6c 6f 63 6b 20 4e 6f 74 69 66 EF: Unlock Notif
3fef0 69 63 61 74 69 6f 6e 0a 2a 2a 20 45 58 50 45 52 ication.** EXPER
3ff00 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 57 68 IMENTAL.**.** Wh
3ff10 65 6e 20 72 75 6e 6e 69 6e 67 20 69 6e 20 73 68 en running in sh
3ff20 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 2c ared-cache mode,
3ff30 20 61 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 a database oper
3ff40 61 74 69 6f 6e 20 6d 61 79 20 66 61 69 6c 20 77 ation may fail w
3ff50 69 74 68 0a 2a 2a 20 61 6e 20 5b 53 51 4c 49 54 ith.** an [SQLIT
3ff60 45 5f 4c 4f 43 4b 45 44 5d 20 65 72 72 6f 72 20 E_LOCKED] error
3ff70 69 66 20 74 68 65 20 72 65 71 75 69 72 65 64 20 if the required
3ff80 6c 6f 63 6b 73 20 6f 6e 20 74 68 65 20 73 68 61 locks on the sha
3ff90 72 65 64 2d 63 61 63 68 65 20 6f 72 0a 2a 2a 20 red-cache or.**
3ffa0 69 6e 64 69 76 69 64 75 61 6c 20 74 61 62 6c 65 individual table
3ffb0 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 68 61 s within the sha
3ffc0 72 65 64 2d 63 61 63 68 65 20 63 61 6e 6e 6f 74 red-cache cannot
3ffd0 20 62 65 20 6f 62 74 61 69 6e 65 64 2e 20 53 65 be obtained. Se
3ffe0 65 0a 2a 2a 20 5b 53 51 4c 69 74 65 20 53 68 61 e.** [SQLite Sha
3fff0 72 65 64 2d 43 61 63 68 65 20 4d 6f 64 65 5d 20 red-Cache Mode]
40000 66 6f 72 20 61 20 64 65 73 63 72 69 70 74 69 6f for a descriptio
40010 6e 20 6f 66 20 73 68 61 72 65 64 2d 63 61 63 68 n of shared-cach
40020 65 20 6c 6f 63 6b 69 6e 67 2e 20 0a 2a 2a 20 54 e locking. .** T
40030 68 69 73 20 41 50 49 20 6d 61 79 20 62 65 20 75 his API may be u
40040 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 sed to register
40050 61 20 63 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 a callback that
40060 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f SQLite will invo
40070 6b 65 20 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 ke .** when the
40080 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 75 72 72 65 connection curre
40090 6e 74 6c 79 20 68 6f 6c 64 69 6e 67 20 74 68 65 ntly holding the
400a0 20 72 65 71 75 69 72 65 64 20 6c 6f 63 6b 20 72 required lock r
400b0 65 6c 69 6e 71 75 69 73 68 65 73 20 69 74 2e 0a elinquishes it..
400c0 2a 2a 20 54 68 69 73 20 41 50 49 20 69 73 20 6f ** This API is o
400d0 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 nly available if
400e0 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 the library was
400f0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 compiled with t
40100 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e he.** [SQLITE_EN
40110 41 42 4c 45 5f 55 4e 4c 4f 43 4b 5f 4e 4f 54 49 ABLE_UNLOCK_NOTI
40120 46 59 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 FY] C-preprocess
40130 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 or symbol define
40140 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 d..**.** See Als
40150 6f 3a 20 5b 55 73 69 6e 67 20 74 68 65 20 53 51 o: [Using the SQ
40160 4c 69 74 65 20 55 6e 6c 6f 63 6b 20 4e 6f 74 69 Lite Unlock Noti
40170 66 69 63 61 74 69 6f 6e 20 46 65 61 74 75 72 65 fication Feature
40180 5d 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65 64 2d ]..**.** Shared-
40190 63 61 63 68 65 20 6c 6f 63 6b 73 20 61 72 65 20 cache locks are
401a0 72 65 6c 65 61 73 65 64 20 77 68 65 6e 20 61 20 released when a
401b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
401c0 69 6f 6e 20 63 6f 6e 63 6c 75 64 65 73 0a 2a 2a ion concludes.**
401d0 20 69 74 73 20 63 75 72 72 65 6e 74 20 74 72 61 its current tra
401e0 6e 73 61 63 74 69 6f 6e 2c 20 65 69 74 68 65 72 nsaction, either
401f0 20 62 79 20 63 6f 6d 6d 69 74 74 69 6e 67 20 69 by committing i
40200 74 20 6f 72 20 72 6f 6c 6c 69 6e 67 20 69 74 20 t or rolling it
40210 62 61 63 6b 2e 20 0a 2a 2a 0a 2a 2a 20 57 68 65 back. .**.** Whe
40220 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 28 n a connection (
40230 6b 6e 6f 77 6e 20 61 73 20 74 68 65 20 62 6c 6f known as the blo
40240 63 6b 65 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 29 cked connection)
40250 20 66 61 69 6c 73 20 74 6f 20 6f 62 74 61 69 6e fails to obtain
40260 20 61 0a 2a 2a 20 73 68 61 72 65 64 2d 63 61 63 a.** shared-cac
40270 68 65 20 6c 6f 63 6b 20 61 6e 64 20 53 51 4c 49 he lock and SQLI
40280 54 45 5f 4c 4f 43 4b 45 44 20 69 73 20 72 65 74 TE_LOCKED is ret
40290 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c urned to the cal
402a0 6c 65 72 2c 20 74 68 65 0a 2a 2a 20 69 64 65 6e ler, the.** iden
402b0 74 69 74 79 20 6f 66 20 74 68 65 20 64 61 74 61 tity of the data
402c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
402d0 28 74 68 65 20 62 6c 6f 63 6b 69 6e 67 20 63 6f (the blocking co
402e0 6e 6e 65 63 74 69 6f 6e 29 20 74 68 61 74 0a 2a nnection) that.*
402f0 2a 20 68 61 73 20 6c 6f 63 6b 65 64 20 74 68 65 * has locked the
40300 20 72 65 71 75 69 72 65 64 20 72 65 73 6f 75 72 required resour
40310 63 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e 74 ce is stored int
40320 65 72 6e 61 6c 6c 79 2e 20 41 66 74 65 72 20 61 ernally. After a
40330 6e 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f n .** applicatio
40340 6e 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 n receives an SQ
40350 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 65 72 72 6f LITE_LOCKED erro
40360 72 2c 20 69 74 20 6d 61 79 20 63 61 6c 6c 20 74 r, it may call t
40370 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 6e he.** sqlite3_un
40380 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 20 6d 65 lock_notify() me
40390 74 68 6f 64 20 77 69 74 68 20 74 68 65 20 62 6c thod with the bl
403a0 6f 63 6b 65 64 20 63 6f 6e 6e 65 63 74 69 6f 6e ocked connection
403b0 20 68 61 6e 64 6c 65 20 61 73 20 0a 2a 2a 20 74 handle as .** t
403c0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
403d0 74 20 74 6f 20 72 65 67 69 73 74 65 72 20 66 6f t to register fo
403e0 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 74 68 61 r a callback tha
403f0 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 t will be invoke
40400 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 62 6c d.** when the bl
40410 6f 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 69 6f ocking connectio
40420 6e 73 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 ns current trans
40430 61 63 74 69 6f 6e 20 69 73 20 63 6f 6e 63 6c 75 action is conclu
40440 64 65 64 2e 20 54 68 65 0a 2a 2a 20 63 61 6c 6c ded. The.** call
40450 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
40460 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 from within the
40470 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 20 6f [sqlite3_step] o
40480 72 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 r [sqlite3_close
40490 5d 0a 2a 2a 20 63 61 6c 6c 20 74 68 61 74 20 63 ].** call that c
404a0 6f 6e 63 6c 75 64 65 73 20 74 68 65 20 62 6c 6f oncludes the blo
404b0 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 69 6f 6e cking connection
404c0 73 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 0a 2a s transaction..*
404d0 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f *.** If sqlite3_
404e0 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 20 unlock_notify()
404f0 69 73 20 63 61 6c 6c 65 64 20 69 6e 20 61 20 6d is called in a m
40500 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 ulti-threaded ap
40510 70 6c 69 63 61 74 69 6f 6e 2c 0a 2a 2a 20 74 68 plication,.** th
40520 65 72 65 20 69 73 20 61 20 63 68 61 6e 63 65 20 ere is a chance
40530 74 68 61 74 20 74 68 65 20 62 6c 6f 63 6b 69 6e that the blockin
40540 67 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 69 6c g connection wil
40550 6c 20 68 61 76 65 20 61 6c 72 65 61 64 79 0a 2a l have already.*
40560 2a 20 63 6f 6e 63 6c 75 64 65 64 20 69 74 73 20 * concluded its
40570 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 79 20 74 transaction by t
40580 68 65 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f he time sqlite3_
40590 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 20 unlock_notify()
405a0 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 49 is invoked..** I
405b0 66 20 74 68 69 73 20 68 61 70 70 65 6e 73 2c 20 f this happens,
405c0 74 68 65 6e 20 74 68 65 20 73 70 65 63 69 66 69 then the specifi
405d0 65 64 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 ed callback is i
405e0 6e 76 6f 6b 65 64 20 69 6d 6d 65 64 69 61 74 65 nvoked immediate
405f0 6c 79 2c 0a 2a 2a 20 66 72 6f 6d 20 77 69 74 68 ly,.** from with
40600 69 6e 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 in the call to s
40610 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f qlite3_unlock_no
40620 74 69 66 79 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 tify()..**.** If
40630 20 74 68 65 20 62 6c 6f 63 6b 65 64 20 63 6f 6e the blocked con
40640 6e 65 63 74 69 6f 6e 20 69 73 20 61 74 74 65 6d nection is attem
40650 70 74 69 6e 67 20 74 6f 20 6f 62 74 61 69 6e 20 pting to obtain
40660 61 20 77 72 69 74 65 2d 6c 6f 63 6b 20 6f 6e 20 a write-lock on
40670 61 0a 2a 2a 20 73 68 61 72 65 64 2d 63 61 63 68 a.** shared-cach
40680 65 20 74 61 62 6c 65 2c 20 61 6e 64 20 6d 6f 72 e table, and mor
40690 65 20 74 68 61 6e 20 6f 6e 65 20 6f 74 68 65 72 e than one other
406a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 75 72 72 connection curr
406b0 65 6e 74 6c 79 20 68 6f 6c 64 73 0a 2a 2a 20 61 ently holds.** a
406c0 20 72 65 61 64 2d 6c 6f 63 6b 20 6f 6e 20 74 68 read-lock on th
406d0 65 20 73 61 6d 65 20 74 61 62 6c 65 2c 20 74 68 e same table, th
406e0 65 6e 20 53 51 4c 69 74 65 20 61 72 62 69 74 72 en SQLite arbitr
406f0 61 72 69 6c 79 20 73 65 6c 65 63 74 73 20 6f 6e arily selects on
40700 65 20 6f 66 20 0a 2a 2a 20 74 68 65 20 6f 74 68 e of .** the oth
40710 65 72 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 74 er connections t
40720 6f 20 75 73 65 20 61 73 20 74 68 65 20 62 6c 6f o use as the blo
40730 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 69 6f 6e cking connection
40740 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 6d 61 ..**.** There ma
40750 79 20 62 65 20 61 74 20 6d 6f 73 74 20 6f 6e 65 y be at most one
40760 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 unlock-notify c
40770 61 6c 6c 62 61 63 6b 20 72 65 67 69 73 74 65 72 allback register
40780 65 64 20 62 79 20 61 20 0a 2a 2a 20 62 6c 6f 63 ed by a .** bloc
40790 6b 65 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 ked connection.
407a0 49 66 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 If sqlite3_unloc
407b0 6b 5f 6e 6f 74 69 66 79 28 29 20 69 73 20 63 61 k_notify() is ca
407c0 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a lled when the.**
407d0 20 62 6c 6f 63 6b 65 64 20 63 6f 6e 6e 65 63 74 blocked connect
407e0 69 6f 6e 20 61 6c 72 65 61 64 79 20 68 61 73 20 ion already has
407f0 61 20 72 65 67 69 73 74 65 72 65 64 20 75 6e 6c a registered unl
40800 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c 6c 62 ock-notify callb
40810 61 63 6b 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ack,.** then the
40820 20 6e 65 77 20 63 61 6c 6c 62 61 63 6b 20 72 65 new callback re
40830 70 6c 61 63 65 73 20 74 68 65 20 6f 6c 64 2e 20 places the old.
40840 49 66 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 If sqlite3_unloc
40850 6b 5f 6e 6f 74 69 66 79 28 29 20 69 73 0a 2a 2a k_notify() is.**
40860 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e called with a N
40870 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 73 20 69 ULL pointer as i
40880 74 73 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 ts second argume
40890 6e 74 2c 20 74 68 65 6e 20 61 6e 79 20 65 78 69 nt, then any exi
408a0 73 74 69 6e 67 0a 2a 2a 20 75 6e 6c 6f 63 6b 2d sting.** unlock-
408b0 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 notify callback
408c0 69 73 20 63 61 6e 63 65 6c 6c 65 64 2e 20 54 68 is cancelled. Th
408d0 65 20 62 6c 6f 63 6b 65 64 20 63 6f 6e 6e 65 63 e blocked connec
408e0 74 69 6f 6e 73 20 0a 2a 2a 20 75 6e 6c 6f 63 6b tions .** unlock
408f0 2d 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b -notify callback
40900 20 6d 61 79 20 61 6c 73 6f 20 62 65 20 63 61 6e may also be can
40910 63 65 6c 65 64 20 62 79 20 63 6c 6f 73 69 6e 67 celed by closing
40920 20 74 68 65 20 62 6c 6f 63 6b 65 64 0a 2a 2a 20 the blocked.**
40930 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 connection using
40940 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 [sqlite3_close(
40950 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 6e )]..**.** The un
40960 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c 6c lock-notify call
40970 62 61 63 6b 20 69 73 20 6e 6f 74 20 72 65 65 6e back is not reen
40980 74 72 61 6e 74 2e 20 49 66 20 61 6e 20 61 70 70 trant. If an app
40990 6c 69 63 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 lication invokes
409a0 0a 2a 2a 20 61 6e 79 20 73 71 6c 69 74 65 33 5f .** any sqlite3_
409b0 78 78 78 20 41 50 49 20 66 75 6e 63 74 69 6f 6e xxx API function
409c0 73 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 61 6e s from within an
409d0 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 unlock-notify c
409e0 61 6c 6c 62 61 63 6b 2c 20 61 0a 2a 2a 20 63 72 allback, a.** cr
409f0 61 73 68 20 6f 72 20 64 65 61 64 6c 6f 63 6b 20 ash or deadlock
40a00 6d 61 79 20 62 65 20 74 68 65 20 72 65 73 75 6c may be the resul
40a10 74 2e 0a 2a 2a 0a 2a 2a 20 55 6e 6c 65 73 73 20 t..**.** Unless
40a20 64 65 61 64 6c 6f 63 6b 20 69 73 20 64 65 74 65 deadlock is dete
40a30 63 74 65 64 20 28 73 65 65 20 62 65 6c 6f 77 29 cted (see below)
40a40 2c 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b , sqlite3_unlock
40a50 5f 6e 6f 74 69 66 79 28 29 20 61 6c 77 61 79 73 _notify() always
40a60 0a 2a 2a 20 72 65 74 75 72 6e 73 20 53 51 4c 49 .** returns SQLI
40a70 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e TE_OK..**.** <b>
40a80 43 61 6c 6c 62 61 63 6b 20 49 6e 76 6f 63 61 74 Callback Invocat
40a90 69 6f 6e 20 44 65 74 61 69 6c 73 3c 2f 62 3e 0a ion Details</b>.
40aa0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 6e 20 75 6e **.** When an un
40ab0 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c 6c lock-notify call
40ac0 62 61 63 6b 20 69 73 20 72 65 67 69 73 74 65 72 back is register
40ad0 65 64 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 ed, the applicat
40ae0 69 6f 6e 20 70 72 6f 76 69 64 65 73 20 61 20 0a ion provides a .
40af0 2a 2a 20 73 69 6e 67 6c 65 20 76 6f 69 64 2a 20 ** single void*
40b00 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 pointer that is
40b10 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 63 61 passed to the ca
40b20 6c 6c 62 61 63 6b 20 77 68 65 6e 20 69 74 20 69 llback when it i
40b30 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 48 6f s invoked..** Ho
40b40 77 65 76 65 72 2c 20 74 68 65 20 73 69 67 6e 61 wever, the signa
40b50 74 75 72 65 20 6f 66 20 74 68 65 20 63 61 6c 6c ture of the call
40b60 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 61 6c back function al
40b70 6c 6f 77 73 20 53 51 4c 69 74 65 20 74 6f 20 70 lows SQLite to p
40b80 61 73 73 0a 2a 2a 20 69 74 20 61 6e 20 61 72 72 ass.** it an arr
40b90 61 79 20 6f 66 20 76 6f 69 64 2a 20 63 6f 6e 74 ay of void* cont
40ba0 65 78 74 20 70 6f 69 6e 74 65 72 73 2e 20 54 68 ext pointers. Th
40bb0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
40bc0 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 61 6e passed to.** an
40bd0 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 unlock-notify c
40be0 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 70 6f 69 allback is a poi
40bf0 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 nter to an array
40c00 20 6f 66 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 of void* pointe
40c10 72 73 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 rs,.** and the s
40c20 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d econd is the num
40c30 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20 69 ber of entries i
40c40 6e 20 74 68 65 20 61 72 72 61 79 2e 0a 2a 2a 0a n the array..**.
40c50 2a 2a 20 57 68 65 6e 20 61 20 62 6c 6f 63 6b 69 ** When a blocki
40c60 6e 67 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 74 ng connections t
40c70 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 6f ransaction is co
40c80 6e 63 6c 75 64 65 64 2c 20 74 68 65 72 65 20 6d ncluded, there m
40c90 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 74 68 ay be.** more th
40ca0 61 6e 20 6f 6e 65 20 62 6c 6f 63 6b 65 64 20 63 an one blocked c
40cb0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 68 onnection that h
40cc0 61 73 20 72 65 67 69 73 74 65 72 65 64 20 66 6f as registered fo
40cd0 72 20 61 6e 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 r an unlock-noti
40ce0 66 79 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 2e 20 fy.** callback.
40cf0 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 73 If two or more s
40d00 75 63 68 20 62 6c 6f 63 6b 65 64 20 63 6f 6e 6e uch blocked conn
40d10 65 63 74 69 6f 6e 73 20 68 61 76 65 20 73 70 65 ections have spe
40d20 63 69 66 69 65 64 20 74 68 65 0a 2a 2a 20 73 61 cified the.** sa
40d30 6d 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 me callback func
40d40 74 69 6f 6e 2c 20 74 68 65 6e 20 69 6e 73 74 65 tion, then inste
40d50 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 ad of invoking t
40d60 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 he callback func
40d70 74 69 6f 6e 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 tion.** multiple
40d80 20 74 69 6d 65 73 2c 20 69 74 20 69 73 20 69 6e times, it is in
40d90 76 6f 6b 65 64 20 6f 6e 63 65 20 77 69 74 68 20 voked once with
40da0 74 68 65 20 73 65 74 20 6f 66 20 76 6f 69 64 2a the set of void*
40db0 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 context pointer
40dc0 73 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 62 s.** specified b
40dd0 79 20 74 68 65 20 62 6c 6f 63 6b 65 64 20 63 6f y the blocked co
40de0 6e 6e 65 63 74 69 6f 6e 73 20 62 75 6e 64 6c 65 nnections bundle
40df0 64 20 74 6f 67 65 74 68 65 72 20 69 6e 74 6f 20 d together into
40e00 61 6e 20 61 72 72 61 79 2e 0a 2a 2a 20 54 68 69 an array..** Thi
40e10 73 20 67 69 76 65 73 20 74 68 65 20 61 70 70 6c s gives the appl
40e20 69 63 61 74 69 6f 6e 20 61 6e 20 6f 70 70 6f 72 ication an oppor
40e30 74 75 6e 69 74 79 20 74 6f 20 70 72 69 6f 72 69 tunity to priori
40e40 74 69 7a 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 tize any actions
40e50 20 0a 2a 2a 20 72 65 6c 61 74 65 64 20 74 6f 20 .** related to
40e60 74 68 65 20 73 65 74 20 6f 66 20 75 6e 62 6c 6f the set of unblo
40e70 63 6b 65 64 20 64 61 74 61 62 61 73 65 20 63 6f cked database co
40e80 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a nnections..**.**
40e90 20 3c 62 3e 44 65 61 64 6c 6f 63 6b 20 44 65 74 <b>Deadlock Det
40ea0 65 63 74 69 6f 6e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a ection</b>.**.**
40eb0 20 41 73 73 75 6d 69 6e 67 20 74 68 61 74 20 61 Assuming that a
40ec0 66 74 65 72 20 72 65 67 69 73 74 65 72 69 6e 67 fter registering
40ed0 20 66 6f 72 20 61 6e 20 75 6e 6c 6f 63 6b 2d 6e for an unlock-n
40ee0 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 61 otify callback a
40ef0 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 77 61 .** database wa
40f00 69 74 73 20 66 6f 72 20 74 68 65 20 63 61 6c 6c its for the call
40f10 62 61 63 6b 20 74 6f 20 62 65 20 69 73 73 75 65 back to be issue
40f20 64 20 62 65 66 6f 72 65 20 74 61 6b 69 6e 67 20 d before taking
40f30 61 6e 79 20 66 75 72 74 68 65 72 0a 2a 2a 20 61 any further.** a
40f40 63 74 69 6f 6e 20 28 61 20 72 65 61 73 6f 6e 61 ction (a reasona
40f50 62 6c 65 20 61 73 73 75 6d 70 74 69 6f 6e 29 2c ble assumption),
40f60 20 74 68 65 6e 20 75 73 69 6e 67 20 74 68 69 73 then using this
40f70 20 41 50 49 20 6d 61 79 20 63 61 75 73 65 20 74 API may cause t
40f80 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f he.** applicatio
40f90 6e 20 74 6f 20 64 65 61 64 6c 6f 63 6b 2e 20 46 n to deadlock. F
40fa0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 63 or example, if c
40fb0 6f 6e 6e 65 63 74 69 6f 6e 20 58 20 69 73 20 77 onnection X is w
40fc0 61 69 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 63 6f aiting for.** co
40fd0 6e 6e 65 63 74 69 6f 6e 20 59 27 73 20 74 72 61 nnection Y's tra
40fe0 6e 73 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 nsaction to be c
40ff0 6f 6e 63 6c 75 64 65 64 2c 20 61 6e 64 20 73 69 oncluded, and si
41000 6d 69 6c 61 72 6c 79 20 63 6f 6e 6e 65 63 74 69 milarly connecti
41010 6f 6e 0a 2a 2a 20 59 20 69 73 20 77 61 69 74 69 on.** Y is waiti
41020 6e 67 20 6f 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e ng on connection
41030 20 58 27 73 20 74 72 61 6e 73 61 63 74 69 6f 6e X's transaction
41040 2c 20 74 68 65 6e 20 6e 65 69 74 68 65 72 20 63 , then neither c
41050 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c onnection.** wil
41060 6c 20 70 72 6f 63 65 65 64 20 61 6e 64 20 74 68 l proceed and th
41070 65 20 73 79 73 74 65 6d 20 6d 61 79 20 72 65 6d e system may rem
41080 61 69 6e 20 64 65 61 64 6c 6f 63 6b 65 64 20 69 ain deadlocked i
41090 6e 64 65 66 69 6e 69 74 65 6c 79 2e 0a 2a 2a 0a ndefinitely..**.
410a0 2a 2a 20 54 6f 20 61 76 6f 69 64 20 74 68 69 73 ** To avoid this
410b0 20 73 63 65 6e 61 72 69 6f 2c 20 74 68 65 20 73 scenario, the s
410c0 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f qlite3_unlock_no
410d0 74 69 66 79 28 29 20 70 65 72 66 6f 72 6d 73 20 tify() performs
410e0 64 65 61 64 6c 6f 63 6b 0a 2a 2a 20 64 65 74 65 deadlock.** dete
410f0 63 74 69 6f 6e 2e 20 49 66 20 61 20 67 69 76 65 ction. If a give
41100 6e 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 n call to sqlite
41110 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 3_unlock_notify(
41120 29 20 77 6f 75 6c 64 20 70 75 74 20 74 68 65 0a ) would put the.
41130 2a 2a 20 73 79 73 74 65 6d 20 69 6e 20 61 20 64 ** system in a d
41140 65 61 64 6c 6f 63 6b 65 64 20 73 74 61 74 65 2c eadlocked state,
41150 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4c 4f 43 then SQLITE_LOC
41160 4b 45 44 20 69 73 20 72 65 74 75 72 6e 65 64 20 KED is returned
41170 61 6e 64 20 6e 6f 0a 2a 2a 20 75 6e 6c 6f 63 6b and no.** unlock
41180 2d 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b -notify callback
41190 20 69 73 20 72 65 67 69 73 74 65 72 65 64 2e 20 is registered.
411a0 54 68 65 20 73 79 73 74 65 6d 20 69 73 20 73 61 The system is sa
411b0 69 64 20 74 6f 20 62 65 20 69 6e 0a 2a 2a 20 61 id to be in.** a
411c0 20 64 65 61 64 6c 6f 63 6b 65 64 20 73 74 61 74 deadlocked stat
411d0 65 20 69 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 e if connection
411e0 41 20 68 61 73 20 72 65 67 69 73 74 65 72 65 64 A has registered
411f0 20 66 6f 72 20 61 6e 20 75 6e 6c 6f 63 6b 2d 6e for an unlock-n
41200 6f 74 69 66 79 0a 2a 2a 20 63 61 6c 6c 62 61 63 otify.** callbac
41210 6b 20 6f 6e 20 74 68 65 20 63 6f 6e 63 6c 75 73 k on the conclus
41220 69 6f 6e 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f ion of connectio
41230 6e 20 42 27 73 20 74 72 61 6e 73 61 63 74 69 6f n B's transactio
41240 6e 2c 20 61 6e 64 20 63 6f 6e 6e 65 63 74 69 6f n, and connectio
41250 6e 0a 2a 2a 20 42 20 68 61 73 20 69 74 73 65 6c n.** B has itsel
41260 66 20 72 65 67 69 73 74 65 72 65 64 20 66 6f 72 f registered for
41270 20 61 6e 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 an unlock-notif
41280 79 20 63 61 6c 6c 62 61 63 6b 20 77 68 65 6e 20 y callback when
41290 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 41 27 connection.** A'
412a0 73 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 s transaction is
412b0 20 63 6f 6e 63 6c 75 64 65 64 2e 20 49 6e 64 69 concluded. Indi
412c0 72 65 63 74 20 64 65 61 64 6c 6f 63 6b 20 69 73 rect deadlock is
412d0 20 61 6c 73 6f 20 64 65 74 65 63 74 65 64 2c 20 also detected,
412e0 73 6f 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d so.** the system
412f0 20 69 73 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 is also conside
41300 72 65 64 20 74 6f 20 62 65 20 64 65 61 64 6c 6f red to be deadlo
41310 63 6b 65 64 20 69 66 20 63 6f 6e 6e 65 63 74 69 cked if connecti
41320 6f 6e 20 42 20 68 61 73 0a 2a 2a 20 72 65 67 69 on B has.** regi
41330 73 74 65 72 65 64 20 66 6f 72 20 61 6e 20 75 6e stered for an un
41340 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c 6c lock-notify call
41350 62 61 63 6b 20 6f 6e 20 74 68 65 20 63 6f 6e 63 back on the conc
41360 6c 75 73 69 6f 6e 20 6f 66 20 63 6f 6e 6e 65 63 lusion of connec
41370 74 69 6f 6e 0a 2a 2a 20 43 27 73 20 74 72 61 6e tion.** C's tran
41380 73 61 63 74 69 6f 6e 2c 20 77 68 65 72 65 20 63 saction, where c
41390 6f 6e 6e 65 63 74 69 6f 6e 20 43 20 69 73 20 77 onnection C is w
413a0 61 69 74 69 6e 67 20 6f 6e 20 63 6f 6e 6e 65 63 aiting on connec
413b0 74 69 6f 6e 20 41 2e 20 41 6e 79 0a 2a 2a 20 6e tion A. Any.** n
413c0 75 6d 62 65 72 20 6f 66 20 6c 65 76 65 6c 73 20 umber of levels
413d0 6f 66 20 69 6e 64 69 72 65 63 74 69 6f 6e 20 61 of indirection a
413e0 72 65 20 61 6c 6c 6f 77 65 64 2e 0a 2a 2a 0a 2a re allowed..**.*
413f0 2a 20 3c 62 3e 54 68 65 20 22 44 52 4f 50 20 54 * <b>The "DROP T
41400 41 42 4c 45 22 20 45 78 63 65 70 74 69 6f 6e 3c ABLE" Exception<
41410 2f 62 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 /b>.**.** When a
41420 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
41430 33 5f 73 74 65 70 28 29 5d 20 72 65 74 75 72 6e 3_step()] return
41440 73 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 2c s SQLITE_LOCKED,
41450 20 69 74 20 69 73 20 61 6c 6d 6f 73 74 20 0a 2a it is almost .*
41460 2a 20 61 6c 77 61 79 73 20 61 70 70 72 6f 70 72 * always appropr
41470 69 61 74 65 20 74 6f 20 63 61 6c 6c 20 73 71 6c iate to call sql
41480 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 ite3_unlock_noti
41490 66 79 28 29 2e 20 54 68 65 72 65 20 69 73 20 68 fy(). There is h
414a0 6f 77 65 76 65 72 2c 0a 2a 2a 20 6f 6e 65 20 65 owever,.** one e
414b0 78 63 65 70 74 69 6f 6e 2e 20 57 68 65 6e 20 65 xception. When e
414c0 78 65 63 75 74 69 6e 67 20 61 20 22 44 52 4f 50 xecuting a "DROP
414d0 20 54 41 42 4c 45 22 20 6f 72 20 22 44 52 4f 50 TABLE" or "DROP
414e0 20 49 4e 44 45 58 22 20 73 74 61 74 65 6d 65 6e INDEX" statemen
414f0 74 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 63 68 65 t,.** SQLite che
41500 63 6b 73 20 69 66 20 74 68 65 72 65 20 61 72 65 cks if there are
41510 20 61 6e 79 20 63 75 72 72 65 6e 74 6c 79 20 65 any currently e
41520 78 65 63 75 74 69 6e 67 20 53 45 4c 45 43 54 20 xecuting SELECT
41530 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 statements.** th
41540 61 74 20 62 65 6c 6f 6e 67 20 74 6f 20 74 68 65 at belong to the
41550 20 73 61 6d 65 20 63 6f 6e 6e 65 63 74 69 6f 6e same connection
41560 2e 20 49 66 20 74 68 65 72 65 20 61 72 65 2c 20 . If there are,
41570 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 69 73 SQLITE_LOCKED is
41580 0a 2a 2a 20 72 65 74 75 72 6e 65 64 2e 20 49 6e .** returned. In
41590 20 74 68 69 73 20 63 61 73 65 20 74 68 65 72 65 this case there
415a0 20 69 73 20 6e 6f 20 22 62 6c 6f 63 6b 69 6e 67 is no "blocking
415b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 22 2c 20 73 6f connection", so
415c0 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c invoking.** sql
415d0 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 ite3_unlock_noti
415e0 66 79 28 29 20 72 65 73 75 6c 74 73 20 69 6e 20 fy() results in
415f0 74 68 65 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 the unlock-notif
41600 79 20 63 61 6c 6c 62 61 63 6b 20 62 65 69 6e 67 y callback being
41610 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 69 6d 6d 65 .** invoked imme
41620 64 69 61 74 65 6c 79 2e 20 49 66 20 74 68 65 20 diately. If the
41630 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 65 6e application then
41640 20 72 65 2d 61 74 74 65 6d 70 74 73 20 74 68 65 re-attempts the
41650 20 22 44 52 4f 50 20 54 41 42 4c 45 22 0a 2a 2a "DROP TABLE".**
41660 20 6f 72 20 22 44 52 4f 50 20 49 4e 44 45 58 22 or "DROP INDEX"
41670 20 71 75 65 72 79 2c 20 61 6e 20 69 6e 66 69 6e query, an infin
41680 69 74 65 20 6c 6f 6f 70 20 6d 69 67 68 74 20 62 ite loop might b
41690 65 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a e the result..**
416a0 0a 2a 2a 20 4f 6e 65 20 77 61 79 20 61 72 6f 75 .** One way arou
416b0 6e 64 20 74 68 69 73 20 70 72 6f 62 6c 65 6d 20 nd this problem
416c0 69 73 20 74 6f 20 63 68 65 63 6b 20 74 68 65 20 is to check the
416d0 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 extended error c
416e0 6f 64 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 ode returned.**
416f0 62 79 20 61 6e 20 73 71 6c 69 74 65 33 5f 73 74 by an sqlite3_st
41700 65 70 28 29 20 63 61 6c 6c 2e 20 49 66 20 74 68 ep() call. If th
41710 65 72 65 20 69 73 20 61 20 62 6c 6f 63 6b 69 6e ere is a blockin
41720 67 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 g connection, th
41730 65 6e 20 74 68 65 0a 2a 2a 20 65 78 74 65 6e 64 en the.** extend
41740 65 64 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 ed error code is
41750 20 73 65 74 20 74 6f 20 53 51 4c 49 54 45 5f 4c set to SQLITE_L
41760 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 OCKED_SHAREDCACH
41770 45 2e 20 4f 74 68 65 72 77 69 73 65 2c 20 69 6e E. Otherwise, in
41780 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 .** the special
41790 22 44 52 4f 50 20 54 41 42 4c 45 2f 49 4e 44 45 "DROP TABLE/INDE
417a0 58 22 20 63 61 73 65 2c 20 74 68 65 20 65 78 74 X" case, the ext
417b0 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 ended error code
417c0 20 69 73 20 6a 75 73 74 20 0a 2a 2a 20 53 51 4c is just .** SQL
417d0 49 54 45 5f 4c 4f 43 4b 45 44 2e 0a 2a 2f 0a 53 ITE_LOCKED..*/.S
417e0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
417f0 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 lite3_unlock_not
41800 69 66 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a ify(. sqlite3 *
41810 70 42 6c 6f 63 6b 65 64 2c 20 20 20 20 20 20 20 pBlocked,
41820 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
41830 20 20 20 2f 2a 20 57 61 69 74 69 6e 67 20 63 6f /* Waiting co
41840 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f nnection */. vo
41850 69 64 20 28 2a 78 4e 6f 74 69 66 79 29 28 76 6f id (*xNotify)(vo
41860 69 64 20 2a 2a 61 70 41 72 67 2c 20 69 6e 74 20 id **apArg, int
41870 6e 41 72 67 29 2c 20 20 20 20 2f 2a 20 43 61 6c nArg), /* Cal
41880 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 lback function t
41890 6f 20 69 6e 76 6f 6b 65 20 2a 2f 0a 20 20 76 6f o invoke */. vo
418a0 69 64 20 2a 70 4e 6f 74 69 66 79 41 72 67 20 20 id *pNotifyArg
418b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
418c0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 /* Arg
418d0 75 6d 65 6e 74 20 74 6f 20 70 61 73 73 20 74 6f ument to pass to
418e0 20 78 4e 6f 74 69 66 79 20 2a 2f 0a 29 3b 0a 0a xNotify */.);..
418f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
41900 20 53 74 72 69 6e 67 20 43 6f 6d 70 61 72 69 73 String Comparis
41910 6f 6e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 on.** EXPERIMENT
41920 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 AL.**.** The [sq
41930 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 lite3_strnicmp()
41940 5d 20 41 50 49 20 61 6c 6c 6f 77 73 20 61 70 70 ] API allows app
41950 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 65 78 lications and ex
41960 74 65 6e 73 69 6f 6e 73 20 74 6f 0a 2a 2a 20 63 tensions to.** c
41970 6f 6d 70 61 72 65 20 74 68 65 20 63 6f 6e 74 65 ompare the conte
41980 6e 74 73 20 6f 66 20 74 77 6f 20 62 75 66 66 65 nts of two buffe
41990 72 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 55 54 rs containing UT
419a0 46 2d 38 20 73 74 72 69 6e 67 73 20 69 6e 20 61 F-8 strings in a
419b0 0a 2a 2a 20 63 61 73 65 2d 69 6e 64 65 6e 64 65 .** case-indende
419c0 6e 74 20 66 61 73 68 69 6f 6e 2c 20 75 73 69 6e nt fashion, usin
419d0 67 20 74 68 65 20 73 61 6d 65 20 64 65 66 69 6e g the same defin
419e0 69 74 69 6f 6e 20 6f 66 20 63 61 73 65 20 69 6e ition of case in
419f0 64 65 70 65 6e 64 65 6e 63 65 20 0a 2a 2a 20 74 dependence .** t
41a00 68 61 74 20 53 51 4c 69 74 65 20 75 73 65 73 20 hat SQLite uses
41a10 69 6e 74 65 72 6e 61 6c 6c 79 20 77 68 65 6e 20 internally when
41a20 63 6f 6d 70 61 72 69 6e 67 20 69 64 65 6e 74 69 comparing identi
41a30 66 69 65 72 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 fiers..*/.SQLITE
41a40 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
41a50 5f 73 74 72 6e 69 63 6d 70 28 63 6f 6e 73 74 20 _strnicmp(const
41a60 63 68 61 72 20 2a 2c 20 63 6f 6e 73 74 20 63 68 char *, const ch
41a70 61 72 20 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a ar *, int);../*.
41a80 2a 2a 20 55 6e 64 6f 20 74 68 65 20 68 61 63 6b ** Undo the hack
41a90 20 74 68 61 74 20 63 6f 6e 76 65 72 74 73 20 66 that converts f
41aa0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 74 79 loating point ty
41ab0 70 65 73 20 74 6f 20 69 6e 74 65 67 65 72 20 66 pes to integer f
41ac0 6f 72 0a 2a 2a 20 62 75 69 6c 64 73 20 6f 6e 20 or.** builds on
41ad0 70 72 6f 63 65 73 73 6f 72 73 20 77 69 74 68 6f processors witho
41ae0 75 74 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e ut floating poin
41af0 74 20 73 75 70 70 6f 72 74 2e 0a 2a 2f 0a 23 69 t support..*/.#i
41b00 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 fdef SQLITE_OMIT
41b10 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a _FLOATING_POINT.
41b20 23 20 75 6e 64 65 66 20 64 6f 75 62 6c 65 0a 23 # undef double.#
41b30 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 5f 5f endif..#ifdef __
41b40 63 70 6c 75 73 70 6c 75 73 0a 7d 20 20 2f 2a 20 cplusplus.} /*
41b50 45 6e 64 20 6f 66 20 74 68 65 20 27 65 78 74 65 End of the 'exte
41b60 72 6e 20 22 43 22 27 20 62 6c 6f 63 6b 20 2a 2f rn "C"' block */
41b70 0a 23 65 6e 64 69 66 0a 23 65 6e 64 69 66 0a 0a .#endif.#endif..