0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65 /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69 e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20 ms copyright to
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a . In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73 , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d sing:.**.** M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 nd not evil..**
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 May you find
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20 forgiveness for
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 give others..**
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65 May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 aking more than
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68 ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65 that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73 library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70 ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43 rograms. If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63 -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64 ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69 ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20 s file, then it
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20 ite, is subject
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64 t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72 should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53 grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74 e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70 arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70 erimental". Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65 y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64 s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20 to SQLite. We
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74 do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 e changes.** to
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65 erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69 ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69 ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67 n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73 est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20 C-language API
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69 r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73 e. This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69 the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20 ve source.** on
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72 how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73 faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 .** The name of
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20 this file under
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68 ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73 e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65 ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74 (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69 ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63 on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20 hanges its name
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61 to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65 s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49 */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 ude <stdarg.h>
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 the definition
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 e can call this
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22 splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74 * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65 y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65 xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 23 69 66 6e 64 65 66 20 53 51 ndif..#ifndef SQ
0710: 4c 49 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e LITE_API.# defin
0720: 65 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e e SQLITE_API.#en
0730: 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 dif.../*.** Thes
0740: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61 e no-op macros a
0750: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74 re used in front
0760: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74 of interfaces t
0770: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20 o mark those.**
0780: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69 interfaces as ei
0790: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20 ther deprecated
07a0: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e or experimental.
07b0: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f New applicatio
07c0: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 ns.** should not
07d0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20 use deprecated
07e0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65 interfaces - the
07f0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f y are support fo
0800: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 r backwards.** c
0810: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c ompatibility onl
0820: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 y. Application
0830: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62 writers should b
0840: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 e aware that.**
0850: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 experimental int
0860: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a erfaces are subj
0870: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e ect to change in
0880: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e point releases.
0890: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 .**.** These mac
08a0: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f ros used to reso
08b0: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b lve to various k
08c0: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 inds of compiler
08d0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 magic that.** w
08e0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61 ould generate wa
08f0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77 rning messages w
0900: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73 hen they were us
0910: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a ed. But that.**
0920: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 compiler magic
0930: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74 ended up generat
0940: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72 ing such a flurr
0950: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73 y of bug reports
0960: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65 .** that we have
0970: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 taken it all ou
0980: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 t and gone back
0990: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a to using simple.
09a0: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a ** noop macros..
09b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
09c0: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65 E_DEPRECATED.#de
09d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45 fine SQLITE_EXPE
09e0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 RIMENTAL../*.**
09f0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d Ensure these sym
0a00: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65 bols were not de
0a10: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72 fined by some pr
0a20: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69 evious header fi
0a30: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 le..*/.#ifdef SQ
0a40: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 LITE_VERSION.# u
0a50: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 ndef SQLITE_VERS
0a60: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 ION.#endif.#ifde
0a70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e f SQLITE_VERSION
0a80: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 _NUMBER.# undef
0a90: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e SQLITE_VERSION_N
0aa0: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a UMBER.#endif../*
0ab0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
0ac0: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 mpile-Time Libra
0ad0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 ry Version Numbe
0ae0: 72 73 20 7b 48 31 30 30 31 30 7d 20 3c 53 36 30 rs {H10010} <S60
0af0: 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 100>.**.** The S
0b00: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 61 6e QLITE_VERSION an
0b10: 64 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e d SQLITE_VERSION
0b20: 5f 4e 55 4d 42 45 52 20 23 64 65 66 69 6e 65 73 _NUMBER #defines
0b30: 20 69 6e 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 in.** the sqlit
0b40: 65 33 2e 68 20 66 69 6c 65 20 73 70 65 63 69 66 e3.h file specif
0b50: 79 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6f 66 y the version of
0b60: 20 53 51 4c 69 74 65 20 77 69 74 68 20 77 68 69 SQLite with whi
0b70: 63 68 0a 2a 2a 20 74 68 61 74 20 68 65 61 64 65 ch.** that heade
0b80: 72 20 66 69 6c 65 20 69 73 20 61 73 73 6f 63 69 r file is associ
0b90: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ated..**.** The
0ba0: 22 76 65 72 73 69 6f 6e 22 20 6f 66 20 53 51 4c "version" of SQL
0bb0: 69 74 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 ite is a string
0bc0: 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 57 2e 58 of the form "W.X
0bd0: 2e 59 22 20 6f 72 20 22 57 2e 58 2e 59 2e 5a 22 .Y" or "W.X.Y.Z"
0be0: 2e 0a 2a 2a 20 54 68 65 20 57 20 76 61 6c 75 65 ..** The W value
0bf0: 20 69 73 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f is major versio
0c00: 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 69 73 20 n number and is
0c10: 61 6c 77 61 79 73 20 33 20 69 6e 20 53 51 4c 69 always 3 in SQLi
0c20: 74 65 33 2e 0a 2a 2a 20 54 68 65 20 57 20 76 61 te3..** The W va
0c30: 6c 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 lue only changes
0c40: 20 77 68 65 6e 20 62 61 63 6b 77 61 72 64 73 20 when backwards
0c50: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 69 73 compatibility is
0c60: 0a 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e 64 20 77 .** broken and w
0c70: 65 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65 76 65 e intend to neve
0c80: 72 20 62 72 65 61 6b 20 62 61 63 6b 77 61 72 64 r break backward
0c90: 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e s compatibility.
0ca0: 0a 2a 2a 20 54 68 65 20 58 20 76 61 6c 75 65 20 .** The X value
0cb0: 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 is the minor ver
0cc0: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 sion number and
0cd0: 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77 68 65 only changes whe
0ce0: 6e 0a 2a 2a 20 74 68 65 72 65 20 61 72 65 20 6d n.** there are m
0cf0: 61 6a 6f 72 20 66 65 61 74 75 72 65 20 65 6e 68 ajor feature enh
0d00: 61 6e 63 65 6d 65 6e 74 73 20 74 68 61 74 20 61 ancements that a
0d10: 72 65 20 66 6f 72 77 61 72 64 73 20 63 6f 6d 70 re forwards comp
0d20: 61 74 69 62 6c 65 0a 2a 2a 20 62 75 74 20 6e 6f atible.** but no
0d30: 74 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 t backwards comp
0d40: 61 74 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 20 59 atible..** The Y
0d50: 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 72 65 value is the re
0d60: 6c 65 61 73 65 20 6e 75 6d 62 65 72 20 61 6e 64 lease number and
0d70: 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 is incremented
0d80: 77 69 74 68 0a 2a 2a 20 65 61 63 68 20 72 65 6c with.** each rel
0d90: 65 61 73 65 20 62 75 74 20 72 65 73 65 74 73 20 ease but resets
0da0: 62 61 63 6b 20 74 6f 20 30 20 77 68 65 6e 65 76 back to 0 whenev
0db0: 65 72 20 58 20 69 73 20 69 6e 63 72 65 6d 65 6e er X is incremen
0dc0: 74 65 64 2e 0a 2a 2a 20 54 68 65 20 5a 20 76 61 ted..** The Z va
0dd0: 6c 75 65 20 6f 6e 6c 79 20 61 70 70 65 61 72 73 lue only appears
0de0: 20 6f 6e 20 62 72 61 6e 63 68 20 72 65 6c 65 61 on branch relea
0df0: 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 ses..**.** The S
0e00: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 QLITE_VERSION_NU
0e10: 4d 42 45 52 20 69 73 20 61 6e 20 69 6e 74 65 67 MBER is an integ
0e20: 65 72 20 74 68 61 74 20 69 73 20 63 6f 6d 70 75 er that is compu
0e30: 74 65 64 20 61 73 0a 2a 2a 20 66 6f 6c 6c 6f 77 ted as.** follow
0e40: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 s:.**.** <blockq
0e50: 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 53 51 uote><pre>.** SQ
0e60: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d LITE_VERSION_NUM
0e70: 42 45 52 20 3d 20 57 2a 31 30 30 30 30 30 30 20 BER = W*1000000
0e80: 2b 20 58 2a 31 30 30 30 20 2b 20 59 0a 2a 2a 20 + X*1000 + Y.**
0e90: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
0ea0: 74 65 3e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 te>.**.** Since
0eb0: 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 version 3.6.18,
0ec0: 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f SQLite source co
0ed0: 64 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f 72 de has been stor
0ee0: 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 ed in the.** <a
0ef0: 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77 href="http://www
0f00: 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f .fossil-scm.org/
0f10: 22 3e 66 6f 73 73 69 6c 20 63 6f 6e 66 69 67 75 ">fossil configu
0f20: 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e ration managemen
0f30: 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e 2e t.** system</a>.
0f40: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 The SQLITE_SOU
0f50: 52 43 45 5f 49 44 0a 2a 2a 20 6d 61 63 72 6f 20 RCE_ID.** macro
0f60: 69 73 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 is a string whic
0f70: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70 h identifies a p
0f80: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d articular check-
0f90: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 in of SQLite.**
0fa0: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 within its confi
0fb0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d guration managem
0fc0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 54 68 65 ent system. The
0fd0: 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 73 string contains
0fe0: 20 74 68 65 0a 2a 2a 20 64 61 74 65 20 61 6e 64 the.** date and
0ff0: 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65 time of the che
1000: 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20 ck-in (UTC) and
1010: 61 6e 20 53 48 41 31 20 68 61 73 68 20 6f 66 20 an SHA1 hash of
1020: 74 68 65 20 65 6e 74 69 72 65 0a 2a 2a 20 73 6f the entire.** so
1030: 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a urce tree..**.**
1040: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
1050: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 te3_libversion()
1060: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c ],.** [sqlite3_l
1070: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 ibversion_number
1080: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f ()], [sqlite3_so
1090: 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73 urceid()],.** [s
10a0: 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d qlite_version()]
10b0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 and [sqlite_sou
10c0: 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2a 0a 2a 2a rce_id()]..**.**
10d0: 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b Requirements: [
10e0: 48 31 30 30 31 31 5d 20 5b 48 31 30 30 31 34 5d H10011] [H10014]
10f0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
1100: 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20 TE_VERSION
1110: 20 20 22 33 2e 36 2e 31 39 22 0a 23 64 65 66 69 "3.6.19".#defi
1120: 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f ne SQLITE_VERSIO
1130: 4e 5f 4e 55 4d 42 45 52 20 33 30 30 36 30 31 39 N_NUMBER 3006019
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 30 2d 31 34 20 31 31 3a 33 33 2009-10-14 11:33
1170: 3a 35 35 20 63 31 64 34 39 39 61 66 63 35 30 64 :55 c1d499afc50d
1180: 35 34 62 33 37 36 39 34 35 62 34 65 66 62 36 35 54b376945b4efb65
1190: 63 35 36 63 37 38 37 61 30 37 33 64 22 0a 0a 2f c56c787a073d"../
11a0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
11b0: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 un-Time Library
11c0: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 20 Version Numbers
11d0: 7b 48 31 30 30 32 30 7d 20 3c 53 36 30 31 30 30 {H10020} <S60100
11e0: 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 >.** KEYWORDS: s
11f0: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 0a 2a qlite3_version.*
1200: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 *.** These inter
1210: 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 faces provide th
1220: 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 e same informati
1230: 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 on as the [SQLIT
1240: 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b E_VERSION],.** [
1250: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e SQLITE_VERSION_N
1260: 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c UMBER], and [SQL
1270: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 23 ITE_SOURCE_ID] #
1280: 64 65 66 69 6e 65 73 20 69 6e 20 74 68 65 20 68 defines in the h
1290: 65 61 64 65 72 2c 0a 2a 2a 20 62 75 74 20 61 72 eader,.** but ar
12a0: 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 e associated wit
12b0: 68 20 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e h the library in
12c0: 73 74 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 stead of the hea
12d0: 64 65 72 20 66 69 6c 65 2e 20 20 43 61 75 74 69 der file. Cauti
12e0: 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 ous.** programme
12f0: 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 rs might include
1300: 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d assert() statem
1310: 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 ents in their ap
1320: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 plication to.**
1330: 76 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 verify that valu
1340: 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 es returned by t
1350: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 hese interfaces
1360: 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 match the macros
1370: 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 in.** the heade
1380: 72 2c 20 61 6e 64 20 74 68 75 73 20 69 6e 73 75 r, and thus insu
1390: 72 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c re that the appl
13a0: 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f ication is.** co
13b0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 mpiled with matc
13c0: 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 hing library and
13d0: 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a header files..*
13e0: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
13f0: 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 ><pre>.** assert
1400: 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 ( sqlite3_libver
1410: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 sion_number()==S
1420: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 QLITE_VERSION_NU
1430: 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 MBER );.** asser
1440: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 t( strcmp(sqlite
1450: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c 3_sourceid(),SQL
1460: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d ITE_SOURCE_ID)==
1470: 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 0 );.** assert(
1480: 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c strcmp(sqlite3_l
1490: 69 62 76 65 72 73 69 6f 6e 2c 53 51 4c 49 54 45 ibversion,SQLITE
14a0: 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a _VERSION)==0 );.
14b0: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
14c0: 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 quote>.**.** The
14d0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 sqlite3_libvers
14e0: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 ion() function r
14f0: 65 74 75 72 6e 73 20 74 68 65 20 73 61 6d 65 20 eturns the same
1500: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 information as i
1510: 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 71 6c 69 s.** in the sqli
1520: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 te3_version[] st
1530: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 ring constant.
1540: 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 The function is
1550: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 provided.** for
1560: 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 use in DLLs sinc
1570: 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61 e DLL users usua
1580: 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 lly do not have
1590: 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74 6f direct access to
15a0: 20 73 74 72 69 6e 67 0a 2a 2a 20 63 6f 6e 73 74 string.** const
15b0: 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65 20 ants within the
15c0: 44 4c 4c 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c DLL. Similarly,
15d0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 the sqlite3_sou
15e0: 72 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e rceid() function
15f0: 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 .** returns the
1600: 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e same information
1610: 20 61 73 20 69 73 20 69 6e 20 74 68 65 20 5b 53 as is in the [S
1620: 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d QLITE_SOURCE_ID]
1630: 20 23 64 65 66 69 6e 65 20 6f 66 0a 2a 2a 20 74 #define of.** t
1640: 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e 0a he header file..
1650: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
1660: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 [sqlite_version(
1670: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 )] and [sqlite_s
1680: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2a 0a ource_id()]..**.
1690: 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
16a0: 20 5b 48 31 30 30 32 31 5d 20 5b 48 31 30 30 32 [H10021] [H1002
16b0: 32 5d 20 5b 48 31 30 30 32 33 5d 0a 2a 2f 0a 53 2] [H10023].*/.S
16c0: 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
16d0: 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 _EXTERN const ch
16e0: 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 ar sqlite3_versi
16f0: 6f 6e 5b 5d 3b 0a 53 51 4c 49 54 45 5f 41 50 49 on[];.SQLITE_API
1700: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c const char *sql
1710: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 ite3_libversion(
1720: 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 void);.SQLITE_AP
1730: 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 I const char *sq
1740: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 76 lite3_sourceid(v
1750: 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 oid);.SQLITE_API
1760: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 int sqlite3_lib
1770: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 version_number(v
1780: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 oid);../*.** CAP
1790: 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 I3REF: Test To S
17a0: 65 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 ee If The Librar
17b0: 79 20 49 73 20 54 68 72 65 61 64 73 61 66 65 20 y Is Threadsafe
17c0: 7b 48 31 30 31 30 30 7d 20 3c 53 36 30 31 30 30 {H10100} <S60100
17d0: 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 >.**.** SQLite c
17e0: 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 an be compiled w
17f0: 69 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d ith or without m
1800: 75 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a utexes. When.**
1810: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
1820: 45 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 EADSAFE] C prepr
1830: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 ocessor macro is
1840: 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 1 or 2, mutexes
1850: 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 .** are enabled
1860: 61 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 and SQLite is th
1870: 72 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 readsafe. When
1880: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 the.** [SQLITE_T
1890: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f HREADSAFE] macro
18a0: 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d is 0, .** the m
18b0: 75 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 utexes are omitt
18c0: 65 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 ed. Without the
18d0: 20 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 mutexes, it is
18e0: 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 not safe.** to u
18f0: 73 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 se SQLite concur
1900: 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 rently from more
1910: 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 than one thread
1920: 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 ..**.** Enabling
1930: 20 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 mutexes incurs
1940: 61 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 a measurable per
1950: 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 formance penalty
1960: 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 ..** So if speed
1970: 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d is of utmost im
1980: 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b portance, it mak
1990: 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 es sense to disa
19a0: 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 ble.** the mutex
19b0: 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 es. But for max
19c0: 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 imum safety, mut
19d0: 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 exes should be e
19e0: 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68 65 20 64 nabled..** The d
19f0: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 efault behavior
1a00: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74 is for mutexes t
1a10: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a o be enabled..**
1a20: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 .** This interfa
1a30: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62 ce can be used b
1a40: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e y an application
1a50: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 to make sure th
1a60: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f at the.** versio
1a70: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 n of SQLite that
1a80: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 it is linking a
1a90: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 gainst was compi
1aa0: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 led with.** the
1ab0: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 desired setting
1ac0: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 of the [SQLITE_T
1ad0: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f HREADSAFE] macro
1ae0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 ..**.** This int
1af0: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f erface only repo
1b00: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 rts on the compi
1b10: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 le-time mutex se
1b20: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 tting.** of the
1b30: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
1b40: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 FE] flag. If SQ
1b50: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
1b60: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f with.** SQLITE_
1b70: 54 48 52 45 41 44 53 41 46 45 3d 31 20 74 68 65 THREADSAFE=1 the
1b80: 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e n mutexes are en
1b90: 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 abled by default
1ba0: 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 but.** can be f
1bb0: 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c ully or partiall
1bc0: 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 y disabled using
1bd0: 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 a call to [sqli
1be0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a te3_config()].**
1bf0: 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73 20 with the verbs
1c00: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
1c10: 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 INGLETHREAD], [S
1c20: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c QLITE_CONFIG_MUL
1c30: 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 TITHREAD],.** or
1c40: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
1c50: 4d 55 54 45 58 5d 2e 20 20 54 68 65 20 72 65 74 MUTEX]. The ret
1c60: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 urn value of thi
1c70: 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 s function shows
1c80: 0a 2a 2a 20 6f 6e 6c 79 20 74 68 65 20 64 65 66 .** only the def
1c90: 61 75 6c 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d ault compile-tim
1ca0: 65 20 73 65 74 74 69 6e 67 2c 20 6e 6f 74 20 61 e setting, not a
1cb0: 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e ny run-time chan
1cc0: 67 65 73 0a 2a 2a 20 74 6f 20 74 68 61 74 20 73 ges.** to that s
1cd0: 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 53 65 etting..**.** Se
1ce0: 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 e the [threading
1cf0: 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 mode] documenta
1d00: 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f tion for additio
1d10: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e nal information.
1d20: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 .**.** Requireme
1d30: 6e 74 73 3a 20 5b 48 31 30 31 30 31 5d 20 5b 48 nts: [H10101] [H
1d40: 31 30 31 30 32 5d 0a 2a 2f 0a 53 51 4c 49 54 45 10102].*/.SQLITE
1d50: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
1d60: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 _threadsafe(void
1d70: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1d80: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e EF: Database Con
1d90: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 20 7b nection Handle {
1da0: 48 31 32 30 30 30 7d 20 3c 53 34 30 32 30 30 3e H12000} <S40200>
1db0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 .** KEYWORDS: {d
1dc0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1dd0: 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f on} {database co
1de0: 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a nnections}.**.**
1df0: 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 Each open SQLit
1e00: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65 e database is re
1e10: 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 presented by a p
1e20: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 ointer to an ins
1e30: 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 tance of.** the
1e40: 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65 opaque structure
1e50: 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 named "sqlite3"
1e60: 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 . It is useful
1e70: 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 to think of an s
1e80: 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 qlite3.** pointe
1e90: 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 r as an object.
1ea0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 The [sqlite3_op
1eb0: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f en()], [sqlite3_
1ec0: 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a open16()], and.*
1ed0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f * [sqlite3_open_
1ee0: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 v2()] interfaces
1ef0: 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 are its constru
1f00: 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 ctors, and [sqli
1f10: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 te3_close()].**
1f20: 69 73 20 69 74 73 20 64 65 73 74 72 75 63 74 6f is its destructo
1f30: 72 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 r. There are ma
1f40: 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61 ny other interfa
1f50: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 ces (such as.**
1f60: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1f70: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 _v2()], [sqlite3
1f80: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
1f90: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ()], and.** [sql
1fa0: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 ite3_busy_timeou
1fb0: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 t()] to name but
1fc0: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65 three) that are
1fd0: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a methods on an.*
1fe0: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 * sqlite3 object
1ff0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
2000: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 uct sqlite3 sqli
2010: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 te3;../*.** CAPI
2020: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 3REF: 64-Bit Int
2030: 65 67 65 72 20 54 79 70 65 73 20 7b 48 31 30 32 eger Types {H102
2040: 30 30 7d 20 3c 53 31 30 31 31 30 3e 0a 2a 2a 20 00} <S10110>.**
2050: 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 KEYWORDS: sqlite
2060: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 _int64 sqlite_ui
2070: 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 nt64.**.** Becau
2080: 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 se there is no c
2090: 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 ross-platform wa
20a0: 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d y to specify 64-
20b0: 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 bit integer type
20c0: 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c s.** SQLite incl
20d0: 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f udes typedefs fo
20e0: 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 r 64-bit signed
20f0: 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 and unsigned int
2100: 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 egers..**.** The
2110: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 sqlite3_int64 a
2120: 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 nd sqlite3_uint6
2130: 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72 4 are the prefer
2140: 72 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 red type definit
2150: 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c ions..** The sql
2160: 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 ite_int64 and sq
2170: 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 lite_uint64 type
2180: 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 s are supported
2190: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a for backwards.**
21a0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f compatibility o
21b0: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 nly..**.** Requi
21c0: 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 32 30 31 rements: [H10201
21d0: 5d 20 5b 48 31 30 32 30 32 5d 0a 2a 2f 0a 23 69 ] [H10202].*/.#i
21e0: 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 fdef SQLITE_INT6
21f0: 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 4_TYPE. typedef
2200: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 SQLITE_INT64_TY
2210: 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b PE sqlite_int64;
2220: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 . typedef unsig
2230: 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 ned SQLITE_INT64
2240: 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e _TYPE sqlite_uin
2250: 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e t64;.#elif defin
2260: 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 ed(_MSC_VER) ||
2270: 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e defined(__BORLAN
2280: 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 DC__). typedef
2290: 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 __int64 sqlite_i
22a0: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 nt64;. typedef
22b0: 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 unsigned __int64
22c0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a sqlite_uint64;.
22d0: 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 #else. typedef
22e0: 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 long long int sq
22f0: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 lite_int64;. ty
2300: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c pedef unsigned l
2310: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c ong long int sql
2320: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 ite_uint64;.#end
2330: 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 if.typedef sqlit
2340: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f e_int64 sqlite3_
2350: 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 int64;.typedef s
2360: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c qlite_uint64 sql
2370: 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a ite3_uint64;../*
2380: 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 .** If compiling
2390: 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 for a processor
23a0: 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 that lacks floa
23b0: 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f ting point suppo
23c0: 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 rt,.** substitut
23d0: 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c e integer for fl
23e0: 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f oating-point..*/
23f0: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f .#ifdef SQLITE_O
2400: 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 MIT_FLOATING_POI
2410: 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 NT.# define doub
2420: 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 le sqlite3_int64
2430: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 .#endif../*.** C
2440: 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 API3REF: Closing
2450: 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e A Database Conn
2460: 65 63 74 69 6f 6e 20 7b 48 31 32 30 31 30 7d 20 ection {H12010}
2470: 3c 53 33 30 31 30 30 3e 3c 53 34 30 32 30 30 3e <S30100><S40200>
2480: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
2490: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72 ine is the destr
24a0: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 uctor for the [s
24b0: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a qlite3] object..
24c0: 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f **.** Applicatio
24d0: 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 ns should [sqlit
24e0: 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 e3_finalize | fi
24f0: 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 nalize] all [pre
2500: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 pared statements
2510: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 ].** and [sqlite
2520: 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 3_blob_close | c
2530: 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 lose] all [BLOB
2540: 68 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 handles] associa
2550: 74 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 ted with.** the
2560: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 [sqlite3] object
2570: 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 prior to attemp
2580: 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 ting to close th
2590: 65 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 65 e object..** The
25a0: 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 [sqlite3_next_s
25b0: 74 6d 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 tmt()] interface
25c0: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
25d0: 6c 6f 63 61 74 65 20 61 6c 6c 0a 2a 2a 20 5b 70 locate all.** [p
25e0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
25f0: 74 73 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 ts] associated w
2600: 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 ith a [database
2610: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 66 20 64 connection] if d
2620: 65 73 69 72 65 64 2e 0a 2a 2a 20 54 79 70 69 63 esired..** Typic
2630: 61 6c 20 63 6f 64 65 20 6d 69 67 68 74 20 6c 6f al code might lo
2640: 6f 6b 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a ok like this:.**
2650: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
2660: 3c 70 72 65 3e 0a 2a 2a 20 73 71 6c 69 74 65 33 <pre>.** sqlite3
2670: 5f 73 74 6d 74 20 2a 70 53 74 6d 74 3b 0a 2a 2a _stmt *pStmt;.**
2680: 20 77 68 69 6c 65 28 20 28 70 53 74 6d 74 20 3d while( (pStmt =
2690: 20 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 sqlite3_next_st
26a0: 6d 74 28 64 62 2c 20 30 29 29 21 3d 30 20 29 7b mt(db, 0))!=0 ){
26b0: 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 73 71 6c .** sql
26c0: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 70 53 ite3_finalize(pS
26d0: 74 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c 2f tmt);.** }.** </
26e0: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
26f0: 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 >.**.** If [sqli
2700: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20 te3_close()] is
2710: 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 20 invoked while a
2720: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f transaction is o
2730: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e pen,.** the tran
2740: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d saction is autom
2750: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 atically rolled
2760: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 back..**.** The
2770: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b C parameter to [
2780: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 sqlite3_close(C)
2790: 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 ] must be either
27a0: 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 a NULL.** point
27b0: 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 er or an [sqlite
27c0: 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 3] object pointe
27d0: 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 r obtained.** fr
27e0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e om [sqlite3_open
27f0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ()], [sqlite3_op
2800: 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b en16()], or.** [
2810: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
2820: 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 )], and not prev
2830: 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a iously closed..*
2840: 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
2850: 73 3a 0a 2a 2a 20 5b 48 31 32 30 31 31 5d 20 5b s:.** [H12011] [
2860: 48 31 32 30 31 32 5d 20 5b 48 31 32 30 31 33 5d H12012] [H12013]
2870: 20 5b 48 31 32 30 31 34 5d 20 5b 48 31 32 30 31 [H12014] [H1201
2880: 35 5d 20 5b 48 31 32 30 31 39 5d 0a 2a 2f 0a 53 5] [H12019].*/.S
2890: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
28a0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 lite3_close(sqli
28b0: 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 te3 *);../*.** T
28c0: 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 61 he type for a ca
28d0: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e llback function.
28e0: 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61 .** This is lega
28f0: 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 65 cy and deprecate
2900: 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64 d. It is includ
2910: 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 ed for historica
2920: 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 l.** compatibili
2930: 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f ty and is not do
2940: 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 cumented..*/.typ
2950: 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 edef int (*sqlit
2960: 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 e3_callback)(voi
2970: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 d*,int,char**, c
2980: 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 har**);../*.** C
2990: 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 API3REF: One-Ste
29a0: 70 20 51 75 65 72 79 20 45 78 65 63 75 74 69 6f p Query Executio
29b0: 6e 20 49 6e 74 65 72 66 61 63 65 20 7b 48 31 32 n Interface {H12
29c0: 31 30 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 100} <S10000>.**
29d0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
29e0: 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 exec() interface
29f0: 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 74 is a convenient
2a00: 20 77 61 79 20 6f 66 20 72 75 6e 6e 69 6e 67 20 way of running
2a10: 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 53 one or more.** S
2a20: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 77 69 QL statements wi
2a30: 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20 thout having to
2a40: 77 72 69 74 65 20 61 20 6c 6f 74 20 6f 66 20 43 write a lot of C
2a50: 20 63 6f 64 65 2e 20 20 54 68 65 20 55 54 46 2d code. The UTF-
2a60: 38 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 53 51 4c 8 encoded.** SQL
2a70: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 statements are
2a80: 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 passed in as the
2a90: 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
2aa0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 r to sqlite3_exe
2ab0: 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 74 61 74 c()..** The stat
2ac0: 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 ements are evalu
2ad0: 61 74 65 64 20 6f 6e 65 20 62 79 20 6f 6e 65 20 ated one by one
2ae0: 75 6e 74 69 6c 20 65 69 74 68 65 72 20 61 6e 20 until either an
2af0: 65 72 72 6f 72 20 6f 72 0a 2a 2a 20 61 6e 20 69 error or.** an i
2b00: 6e 74 65 72 72 75 70 74 20 69 73 20 65 6e 63 6f nterrupt is enco
2b10: 75 6e 74 65 72 65 64 2c 20 6f 72 20 75 6e 74 69 untered, or unti
2b20: 6c 20 74 68 65 79 20 61 72 65 20 61 6c 6c 20 64 l they are all d
2b30: 6f 6e 65 2e 20 20 54 68 65 20 33 72 64 20 70 61 one. The 3rd pa
2b40: 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 61 6e rameter.** is an
2b50: 20 6f 70 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 optional callba
2b60: 63 6b 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b ck that is invok
2b70: 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 ed once for each
2b80: 20 72 6f 77 20 6f 66 20 61 6e 79 20 71 75 65 72 row of any quer
2b90: 79 0a 2a 2a 20 72 65 73 75 6c 74 73 20 70 72 6f y.** results pro
2ba0: 64 75 63 65 64 20 62 79 20 74 68 65 20 53 51 4c duced by the SQL
2bb0: 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 54 68 statements. Th
2bc0: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 5th parameter
2bd0: 74 65 6c 6c 73 20 77 68 65 72 65 0a 2a 2a 20 74 tells where.** t
2be0: 6f 20 77 72 69 74 65 20 61 6e 79 20 65 72 72 6f o write any erro
2bf0: 72 20 6d 65 73 73 61 67 65 73 2e 0a 2a 2a 0a 2a r messages..**.*
2c00: 2a 20 54 68 65 20 65 72 72 6f 72 20 6d 65 73 73 * The error mess
2c10: 61 67 65 20 70 61 73 73 65 64 20 62 61 63 6b 20 age passed back
2c20: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 through the 5th
2c30: 70 61 72 61 6d 65 74 65 72 20 69 73 20 68 65 6c parameter is hel
2c40: 64 0a 2a 2a 20 69 6e 20 6d 65 6d 6f 72 79 20 6f d.** in memory o
2c50: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
2c60: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e lite3_malloc()].
2c70: 20 20 54 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d To avoid a mem
2c80: 6f 72 79 20 6c 65 61 6b 2c 0a 2a 2a 20 74 68 65 ory leak,.** the
2c90: 20 63 61 6c 6c 69 6e 67 20 61 70 70 6c 69 63 61 calling applica
2ca0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 63 61 6c 6c tion should call
2cb0: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
2cc0: 5d 20 6f 6e 20 61 6e 79 20 65 72 72 6f 72 0a 2a ] on any error.*
2cd0: 2a 20 6d 65 73 73 61 67 65 20 72 65 74 75 72 6e * message return
2ce0: 65 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 ed through the 5
2cf0: 74 68 20 70 61 72 61 6d 65 74 65 72 20 77 68 65 th parameter whe
2d00: 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 n it has finishe
2d10: 64 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 65 d using.** the e
2d20: 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a rror message..**
2d30: 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 .** If the SQL s
2d40: 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 tatement in the
2d50: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 2nd parameter is
2d60: 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 NULL or an empt
2d70: 79 20 73 74 72 69 6e 67 0a 2a 2a 20 6f 72 20 61 y string.** or a
2d80: 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 string containi
2d90: 6e 67 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 ng only whitespa
2da0: 63 65 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 2c ce and comments,
2db0: 20 74 68 65 6e 20 6e 6f 20 53 51 4c 0a 2a 2a 20 then no SQL.**
2dc0: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 statements are e
2dd0: 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65 valuated and the
2de0: 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 database is not
2df0: 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 changed..**.**
2e00: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 The sqlite3_exec
2e10: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 () interface is
2e20: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 74 implemented in t
2e30: 65 72 6d 73 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 erms of.** [sqli
2e40: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
2e50: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ], [sqlite3_step
2e60: 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 ()], and [sqlite
2e70: 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 3_finalize()]..*
2e80: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 * The sqlite3_ex
2e90: 65 63 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 ec() routine doe
2ea0: 73 20 6e 6f 74 68 69 6e 67 20 74 6f 20 74 68 65 s nothing to the
2eb0: 20 64 61 74 61 62 61 73 65 20 74 68 61 74 20 63 database that c
2ec0: 61 6e 6e 6f 74 20 62 65 20 64 6f 6e 65 0a 2a 2a annot be done.**
2ed0: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 by [sqlite3_pre
2ee0: 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c pare_v2()], [sql
2ef0: 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e ite3_step()], an
2f00: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c d [sqlite3_final
2f10: 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 ize()]..**.** Th
2f20: 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
2f30: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 r to [sqlite3_ex
2f40: 65 63 28 29 5d 20 6d 75 73 74 20 62 65 20 61 6e ec()] must be an
2f50: 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 0a valid and open.
2f60: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
2f70: 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 nection]..**.**
2f80: 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e The database con
2f90: 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 nection must not
2fa0: 20 62 65 20 63 6c 6f 73 65 64 20 77 68 69 6c 65 be closed while
2fb0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 .** [sqlite3_exe
2fc0: 63 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 2e c()] is running.
2fd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 .**.** The calli
2fe0: 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 ng function shou
2ff0: 6c 64 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f ld use [sqlite3_
3000: 66 72 65 65 28 29 5d 20 74 6f 20 66 72 65 65 0a free()] to free.
3010: 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 ** the memory th
3020: 61 74 20 2a 65 72 72 6d 73 67 20 69 73 20 6c 65 at *errmsg is le
3030: 66 74 20 70 6f 69 6e 74 69 6e 67 20 61 74 20 6f ft pointing at o
3040: 6e 63 65 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a nce the error.**
3050: 20 6d 65 73 73 61 67 65 20 69 73 20 6e 6f 20 6c message is no l
3060: 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a onger needed..**
3070: 0a 2a 2a 20 54 68 65 20 53 51 4c 20 73 74 61 74 .** The SQL stat
3080: 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 20 74 68 ement text in th
3090: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 e 2nd parameter
30a0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 to [sqlite3_exec
30b0: 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 72 65 6d 61 ()].** must rema
30c0: 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 77 68 69 in unchanged whi
30d0: 6c 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 le [sqlite3_exec
30e0: 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a ()] is running..
30f0: 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
3100: 74 73 3a 0a 2a 2a 20 5b 48 31 32 31 30 31 5d 20 ts:.** [H12101]
3110: 5b 48 31 32 31 30 32 5d 20 5b 48 31 32 31 30 34 [H12102] [H12104
3120: 5d 20 5b 48 31 32 31 30 35 5d 20 5b 48 31 32 31 ] [H12105] [H121
3130: 30 37 5d 20 5b 48 31 32 31 31 30 5d 20 5b 48 31 07] [H12110] [H1
3140: 32 31 31 33 5d 20 5b 48 31 32 31 31 36 5d 0a 2a 2113] [H12116].*
3150: 2a 20 5b 48 31 32 31 31 39 5d 20 5b 48 31 32 31 * [H12119] [H121
3160: 32 32 5d 20 5b 48 31 32 31 32 35 5d 20 5b 48 31 22] [H12125] [H1
3170: 32 31 33 31 5d 20 5b 48 31 32 31 33 34 5d 20 5b 2131] [H12134] [
3180: 48 31 32 31 33 37 5d 20 5b 48 31 32 31 33 38 5d H12137] [H12138]
3190: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
31a0: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 nt sqlite3_exec(
31b0: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 . sqlite3*,
31c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
31d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
31e0: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 An open databas
31f0: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
3200: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 r *sql,
3210: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3220: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 /* SQL to be e
3230: 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e valuated */. in
3240: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f t (*callback)(vo
3250: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 id*,int,char**,c
3260: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c har**), /* Call
3270: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f back function */
3280: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 . void *,
3290: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
32a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
32b0: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 1st argument to
32c0: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 callback */. c
32d0: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 har **errmsg
32e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
32f0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 /* Err
3300: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 or msg written h
3310: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a ere */.);../*.**
3320: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c CAPI3REF: Resul
3330: 74 20 43 6f 64 65 73 20 7b 48 31 30 32 31 30 7d t Codes {H10210}
3340: 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 <S10700>.** KEY
3350: 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b WORDS: SQLITE_OK
3360: 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 {error code} {e
3370: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b rror codes}.** K
3380: 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 EYWORDS: {result
3390: 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 code} {result c
33a0: 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 odes}.**.** Many
33b0: 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e SQLite function
33c0: 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 s return an inte
33d0: 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 ger result code
33e0: 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f from the set sho
33f0: 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 wn.** here in or
3400: 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 73 der to indicates
3410: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c success or fail
3420: 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 ure..**.** New e
3430: 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 rror codes may b
3440: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
3450: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 e versions of SQ
3460: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 Lite..**.** See
3470: 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f also: [SQLITE_IO
3480: 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e ERR_READ | exten
3490: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
34a0: 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ].*/.#define SQL
34b0: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 ITE_OK
34c0: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66 0 /* Successf
34d0: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 ul result */./*
34e0: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 beginning-of-err
34f0: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 or-codes */.#def
3500: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 ine SQLITE_ERROR
3510: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53 1 /* S
3520: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 QL error or miss
3530: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a ing database */.
3540: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
3550: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20 NTERNAL 2
3560: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 /* Internal logi
3570: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 c error in SQLit
3580: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e */.#define SQL
3590: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20 ITE_PERM
35a0: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70 3 /* Access p
35b0: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 ermission denied
35c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
35d0: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20 TE_ABORT
35e0: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 4 /* Callback
35f0: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65 routine requeste
3600: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 d an abort */.#d
3610: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 efine SQLITE_BUS
3620: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a Y 5 /*
3630: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69 The database fi
3640: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a le is locked */.
3650: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
3660: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20 OCKED 6
3670: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68 /* A table in th
3680: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f e database is lo
3690: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 cked */.#define
36a0: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 SQLITE_NOMEM
36b0: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 7 /* A mal
36c0: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a loc() failed */.
36d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
36e0: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 EADONLY 8
36f0: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72 /* Attempt to wr
3700: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 ite a readonly d
3710: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 atabase */.#defi
3720: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 ne SQLITE_INTERR
3730: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 UPT 9 /* Op
3740: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 eration terminat
3750: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e ed by sqlite3_in
3760: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 terrupt()*/.#def
3770: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
3780: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53 10 /* S
3790: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b ome kind of disk
37a0: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 I/O error occur
37b0: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 red */.#define S
37c0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20 QLITE_CORRUPT
37d0: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61 11 /* The da
37e0: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67 tabase disk imag
37f0: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a e is malformed *
3800: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
3810: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20 _NOTFOUND 12
3820: 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 /* NOT USED. T
3830: 61 62 6c 65 20 6f 72 20 72 65 63 6f 72 64 20 6e able or record n
3840: 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 ot found */.#def
3850: 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 ine SQLITE_FULL
3860: 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49 13 /* I
3870: 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 nsertion failed
3880: 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73 65 because database
3890: 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 is full */.#def
38a0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f ine SQLITE_CANTO
38b0: 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55 PEN 14 /* U
38c0: 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 nable to open th
38d0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
38e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
38f0: 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 E_PROTOCOL 15
3900: 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 /* NOT USED.
3910: 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 Database lock pr
3920: 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a otocol error */.
3930: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 #define SQLITE_E
3940: 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 MPTY 16
3950: 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65 /* Database is e
3960: 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 mpty */.#define
3970: 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 SQLITE_SCHEMA
3980: 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 17 /* The d
3990: 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 atabase schema c
39a0: 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e hanged */.#defin
39b0: 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 e SQLITE_TOOBIG
39c0: 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 18 /* Str
39d0: 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 ing or BLOB exce
39e0: 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a eds size limit *
39f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
3a00: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 _CONSTRAINT 19
3a10: 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 /* Abort due t
3a20: 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f o constraint vio
3a30: 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e lation */.#defin
3a40: 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 e SQLITE_MISMATC
3a50: 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 H 20 /* Dat
3a60: 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 a type mismatch
3a70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
3a80: 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 E_MISUSE 21
3a90: 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 /* Library us
3aa0: 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a ed incorrectly *
3ab0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
3ac0: 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 _NOLFS 22
3ad0: 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 /* Uses OS fea
3ae0: 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 tures not suppor
3af0: 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 ted on host */.#
3b00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 define SQLITE_AU
3b10: 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f TH 23 /
3b20: 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 * Authorization
3b30: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e denied */.#defin
3b40: 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 e SQLITE_FORMAT
3b50: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 24 /* Aux
3b60: 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20 iliary database
3b70: 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a format error */.
3b80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
3b90: 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20 ANGE 25
3ba0: 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 /* 2nd parameter
3bb0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
3bc0: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f out of range */
3bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3be0: 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20 NOTADB 26
3bf0: 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 /* File opened
3c00: 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 that is not a da
3c10: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 tabase file */.#
3c20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f define SQLITE_RO
3c30: 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f W 100 /
3c40: 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 * sqlite3_step()
3c50: 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 has another row
3c60: 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e ready */.#defin
3c70: 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 e SQLITE_DONE
3c80: 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 101 /* sql
3c90: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 ite3_step() has
3ca0: 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 finished executi
3cb0: 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d ng */./* end-of-
3cc0: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a error-codes */..
3cd0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
3ce0: 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 Extended Result
3cf0: 43 6f 64 65 73 20 7b 48 31 30 32 32 30 7d 20 3c Codes {H10220} <
3d00: 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f S10700>.** KEYWO
3d10: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 65 RDS: {extended e
3d20: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74 65 rror code} {exte
3d30: 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 nded error codes
3d40: 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b }.** KEYWORDS: {
3d50: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
3d60: 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 code} {extended
3d70: 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a result codes}.**
3d80: 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 .** In its defau
3d90: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e lt configuration
3da0: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 , SQLite API rou
3db0: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 tines return one
3dc0: 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a 2a of 26 integer.*
3dd0: 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 * [SQLITE_OK | r
3de0: 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 esult codes]. H
3df0: 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e owever, experien
3e00: 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 ce has shown tha
3e10: 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 t many of.** the
3e20: 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 se result codes
3e30: 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 are too coarse-g
3e40: 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f rained. They do
3e50: 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a not provide as.
3e60: 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 ** much informat
3e70: 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 ion about proble
3e80: 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 ms as programmer
3e90: 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 s might like. I
3ea0: 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a n an effort to.*
3eb0: 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 * address this,
3ec0: 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f newer versions o
3ed0: 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f f SQLite (versio
3ee0: 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 n 3.3.8 and late
3ef0: 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 r) include.** su
3f00: 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 pport for additi
3f10: 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 onal result code
3f20: 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d s that provide m
3f30: 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 ore detailed inf
3f40: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 ormation.** abou
3f50: 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65 78 t errors. The ex
3f60: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
3f70: 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 des are enabled
3f80: 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f or disabled.** o
3f90: 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73 65 n a per database
3fa0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 connection basi
3fb0: 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b s using the.** [
3fc0: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
3fd0: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d _result_codes()]
3fe0: 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 API..**.** Some
3ff0: 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c of the availabl
4000: 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c e extended resul
4010: 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74 t codes are list
4020: 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 ed here..** One
4030: 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20 6e may expect the n
4040: 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64 65 umber of extende
4050: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 77 d result codes w
4060: 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a ill be expand.**
4070: 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f 66 over time. Sof
4080: 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73 20 tware that uses
4090: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
40a0: 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78 70 codes should exp
40b0: 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 ect.** to see ne
40c0: 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 69 w result codes i
40d0: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
40e0: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a s of SQLite..**.
40f0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b ** The SQLITE_OK
4100: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c result code wil
4110: 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e l never be exten
4120: 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c ded. It will al
4130: 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 ways.** be exact
4140: 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66 ly zero..*/.#def
4150: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
4160: 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 _READ
4170: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
4180: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 | (1<<8)).#defi
4190: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
41a0: 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 SHORT_READ
41b0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
41c0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (2<<8)).#defin
41d0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 e SQLITE_IOERR_W
41e0: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 RITE
41f0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
4200: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (3<<8)).#define
4210: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 SQLITE_IOERR_FS
4220: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 YNC
4230: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
4240: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (4<<8)).#define
4250: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 SQLITE_IOERR_DIR
4260: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 _FSYNC (
4270: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
4280: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 5<<8)).#define S
4290: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e QLITE_IOERR_TRUN
42a0: 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53 CATE (S
42b0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 QLITE_IOERR | (6
42c0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
42d0: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 LITE_IOERR_FSTAT
42e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
42f0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c LITE_IOERR | (7<
4300: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
4310: 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b ITE_IOERR_UNLOCK
4320: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
4330: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c ITE_IOERR | (8<<
4340: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4350: 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 TE_IOERR_RDLOCK
4360: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
4370: 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 TE_IOERR | (9<<8
4380: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
4390: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 E_IOERR_DELETE
43a0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
43b0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 E_IOERR | (10<<8
43c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
43d0: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 E_IOERR_BLOCKED
43e0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
43f0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 E_IOERR | (11<<8
4400: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
4410: 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 E_IOERR_NOMEM
4420: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
4430: 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 E_IOERR | (12<<8
4440: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
4450: 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 E_IOERR_ACCESS
4460: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
4470: 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 E_IOERR | (13<<8
4480: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
4490: 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 E_IOERR_CHECKRES
44a0: 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 ERVEDLOCK (SQLIT
44b0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 E_IOERR | (14<<8
44c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
44d0: 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 E_IOERR_LOCK
44e0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
44f0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 E_IOERR | (15<<8
4500: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
4510: 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 E_IOERR_CLOSE
4520: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
4530: 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 E_IOERR | (16<<8
4540: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
4550: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 E_IOERR_DIR_CLOS
4560: 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 E (SQLIT
4570: 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 E_IOERR | (17<<8
4580: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
4590: 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 E_LOCKED_SHAREDC
45a0: 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 ACHE (SQLIT
45b0: 45 5f 4c 4f 43 4b 45 44 20 7c 20 28 31 3c 3c 38 E_LOCKED | (1<<8
45c0: 29 20 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 ) )../*.** CAPI3
45d0: 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 REF: Flags For F
45e0: 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 ile Open Operati
45f0: 6f 6e 73 20 7b 48 31 30 32 33 30 7d 20 3c 48 31 ons {H10230} <H1
4600: 31 31 32 30 3e 20 3c 48 31 32 37 30 30 3e 0a 2a 1120> <H12700>.*
4610: 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 *.** These bit v
4620: 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 alues are intend
4630: 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 ed for use in th
4640: 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 e.** 3rd paramet
4650: 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 er to the [sqlit
4660: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e e3_open_v2()] in
4670: 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 terface and.** i
4680: 6e 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 n the 4th parame
4690: 74 65 72 20 74 6f 20 74 68 65 20 78 4f 70 65 6e ter to the xOpen
46a0: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a method of the.*
46b0: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 * [sqlite3_vfs]
46c0: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 object..*/.#defi
46d0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 ne SQLITE_OPEN_R
46e0: 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 EADONLY
46f0: 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 0x00000001 /* O
4700: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
4710: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 en_v2() */.#defi
4720: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 ne SQLITE_OPEN_R
4730: 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20 20 EADWRITE
4740: 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 0x00000002 /* O
4750: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
4760: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 en_v2() */.#defi
4770: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 ne SQLITE_OPEN_C
4780: 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20 20 REATE
4790: 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 0x00000004 /* O
47a0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
47b0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 en_v2() */.#defi
47c0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 ne SQLITE_OPEN_D
47d0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 ELETEONCLOSE
47e0: 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56 0x00000008 /* V
47f0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
4800: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 ne SQLITE_OPEN_E
4810: 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 XCLUSIVE
4820: 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56 0x00000010 /* V
4830: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
4840: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d ne SQLITE_OPEN_M
4850: 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 AIN_DB
4860: 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56 0x00000100 /* V
4870: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
4880: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 ne SQLITE_OPEN_T
4890: 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 EMP_DB
48a0: 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56 0x00000200 /* V
48b0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
48c0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 ne SQLITE_OPEN_T
48d0: 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 RANSIENT_DB
48e0: 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56 0x00000400 /* V
48f0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
4900: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d ne SQLITE_OPEN_M
4910: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 AIN_JOURNAL
4920: 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56 0x00000800 /* V
4930: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
4940: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 ne SQLITE_OPEN_T
4950: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 EMP_JOURNAL
4960: 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56 0x00001000 /* V
4970: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
4980: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 ne SQLITE_OPEN_S
4990: 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 UBJOURNAL
49a0: 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56 0x00002000 /* V
49b0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
49c0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d ne SQLITE_OPEN_M
49d0: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 ASTER_JOURNAL
49e0: 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56 0x00004000 /* V
49f0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 FS only */.#defi
4a00: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e ne SQLITE_OPEN_N
4a10: 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 20 OMUTEX
4a20: 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 0x00008000 /* O
4a30: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
4a40: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 en_v2() */.#defi
4a50: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 ne SQLITE_OPEN_F
4a60: 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20 ULLMUTEX
4a70: 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 0x00010000 /* O
4a80: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
4a90: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 en_v2() */.#defi
4aa0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 ne SQLITE_OPEN_S
4ab0: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 HAREDCACHE
4ac0: 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 0x00020000 /* O
4ad0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
4ae0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 en_v2() */.#defi
4af0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 ne SQLITE_OPEN_P
4b00: 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20 20 RIVATECACHE
4b10: 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 0x00040000 /* O
4b20: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 k for sqlite3_op
4b30: 65 6e 5f 76 32 28 29 20 2a 2f 0a 0a 2f 2a 0a 2a en_v2() */../*.*
4b40: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 * CAPI3REF: Devi
4b50: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 ce Characteristi
4b60: 63 73 20 7b 48 31 30 32 34 30 7d 20 3c 48 31 31 cs {H10240} <H11
4b70: 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 120>.**.** The x
4b80: 44 65 76 69 63 65 43 61 70 61 62 69 6c 69 74 69 DeviceCapabiliti
4b90: 65 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 es method of the
4ba0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
4bb0: 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 hods].** object
4bc0: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 returns an integ
4bd0: 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 er which is a ve
4be0: 63 74 6f 72 20 6f 66 20 74 68 65 20 74 68 65 73 ctor of the thes
4bf0: 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 e.** bit values
4c00: 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 expressing I/O c
4c10: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f haracteristics o
4c20: 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 f the mass stora
4c30: 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 ge.** device tha
4c40: 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 t holds the file
4c50: 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 that the [sqlit
4c60: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a e3_io_methods].*
4c70: 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a * refers to..**.
4c80: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f ** The SQLITE_IO
4c90: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 CAP_ATOMIC prope
4ca0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 rty means that a
4cb0: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 ll writes of.**
4cc0: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f any size are ato
4cd0: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 mic. The SQLITE
4ce0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e _IOCAP_ATOMICnnn
4cf0: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 values.** mean
4d00: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 that writes of b
4d10: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e locks that are n
4d20: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 nn bytes in size
4d30: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 and.** are alig
4d40: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 ned to an addres
4d50: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e s which is an in
4d60: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f teger multiple o
4d70: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f f.** nnn are ato
4d80: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 mic. The SQLITE
4d90: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 _IOCAP_SAFE_APPE
4da0: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a ND value means.*
4db0: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 * that when data
4dc0: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 is appended to
4dd0: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 a file, the data
4de0: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 is appended.**
4df0: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 first then the s
4e00: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 ize of the file
4e10: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 is extended, nev
4e20: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 er the other.**
4e30: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 way around. The
4e40: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 SQLITE_IOCAP_SE
4e50: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 QUENTIAL propert
4e60: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 y means that.**
4e70: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 information is w
4e80: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 ritten to disk i
4e90: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 n the same order
4ea0: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 as calls.** to
4eb0: 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 xWrite()..*/.#de
4ec0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
4ed0: 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 P_ATOMIC
4ee0: 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 0x00000001.#de
4ef0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
4f00: 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 P_ATOMIC512
4f10: 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 0x00000002.#de
4f20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
4f30: 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 P_ATOMIC1K
4f40: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 0x00000004.#de
4f50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
4f60: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 P_ATOMIC2K
4f70: 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 0x00000008.#de
4f80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
4f90: 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 P_ATOMIC4K
4fa0: 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 0x00000010.#de
4fb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
4fc0: 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 P_ATOMIC8K
4fd0: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 0x00000020.#de
4fe0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
4ff0: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 P_ATOMIC16K
5000: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 0x00000040.#de
5010: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
5020: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 P_ATOMIC32K
5030: 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 0x00000080.#de
5040: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
5050: 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 P_ATOMIC64K
5060: 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 0x00000100.#de
5070: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
5080: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 P_SAFE_APPEND
5090: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 0x00000200.#de
50a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
50b0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 P_SEQUENTIAL
50c0: 20 20 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0x00000400../*
50d0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 .** CAPI3REF: Fi
50e0: 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c le Locking Level
50f0: 73 20 7b 48 31 30 32 35 30 7d 20 3c 48 31 31 31 s {H10250} <H111
5100: 32 30 3e 20 3c 48 31 31 33 31 30 3e 0a 2a 2a 0a 20> <H11310>.**.
5110: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f ** SQLite uses o
5120: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 ne of these inte
5130: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 ger values as th
5140: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 e second.** argu
5150: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 ment to calls it
5160: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c makes to the xL
5170: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 ock() and xUnloc
5180: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f k() methods.** o
5190: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f f an [sqlite3_io
51a0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 _methods] object
51b0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
51c0: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 ITE_LOCK_NONE
51d0: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 0.#define
51e0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 SQLITE_LOCK_SHA
51f0: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 RED 1.#de
5200: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b fine SQLITE_LOCK
5210: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 _RESERVED 2
5220: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5230: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 LOCK_PENDING
5240: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 3.#define SQL
5250: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 ITE_LOCK_EXCLUSI
5260: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 VE 4../*.**
5270: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 CAPI3REF: Synchr
5280: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 onization Type F
5290: 6c 61 67 73 20 7b 48 31 30 32 36 30 7d 20 3c 48 lags {H10260} <H
52a0: 31 31 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 11120>.**.** Whe
52b0: 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 n SQLite invokes
52c0: 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 the xSync() met
52d0: 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 hod of an.** [sq
52e0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
52f0: 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 ] object it uses
5300: 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f a combination o
5310: 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 f.** these integ
5320: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 er values as the
5330: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
5340: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 ..**.** When the
5350: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 SQLITE_SYNC_DAT
5360: 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 AONLY flag is us
5370: 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 ed, it means tha
5380: 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 t the.** sync op
5390: 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 eration only nee
53a0: 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 ds to flush data
53b0: 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 to mass storage
53c0: 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f . Inode.** info
53d0: 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 rmation need not
53e0: 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 be flushed. If
53f0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 the lower four b
5400: 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a its of the flag.
5410: 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f ** equal SQLITE_
5420: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 SYNC_NORMAL, tha
5430: 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e t means to use n
5440: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 ormal fsync() se
5450: 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 mantics..** If t
5460: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 he lower four bi
5470: 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f ts equal SQLITE_
5480: 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 SYNC_FULL, that
5490: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 means.** to use
54a0: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 Mac OS X style f
54b0: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 ullsync instead
54c0: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 of fsync()..*/.#
54d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 define SQLITE_SY
54e0: 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 NC_NORMAL
54f0: 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 0x00002.#define
5500: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c SQLITE_SYNC_FUL
5510: 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 L 0x000
5520: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 03.#define SQLIT
5530: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 E_SYNC_DATAONLY
5540: 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0x00010../*
5550: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 .** CAPI3REF: OS
5560: 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 Interface Open
5570: 46 69 6c 65 20 48 61 6e 64 6c 65 20 7b 48 31 31 File Handle {H11
5580: 31 31 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 110} <S20110>.**
5590: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f .** An [sqlite3_
55a0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 file] object rep
55b0: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 resents an open
55c0: 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 file in the .**
55d0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f [sqlite3_vfs | O
55e0: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 S interface laye
55f0: 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 r]. Individual
5600: 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 OS interface.**
5610: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
5620: 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 will.** want to
5630: 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 subclass this ob
5640: 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e ject by appendin
5650: 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 g additional fie
5660: 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 lds.** for their
5670: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 own use. The p
5680: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 Methods entry is
5690: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
56a0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f .** [sqlite3_io_
56b0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 methods] object
56c0: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 that defines met
56d0: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d hods for perform
56e0: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 ing.** I/O opera
56f0: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 tions on the ope
5700: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 n file..*/.typed
5710: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
5720: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 3_file sqlite3_f
5730: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 ile;.struct sqli
5740: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e te3_file {. con
5750: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 st struct sqlite
5760: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 3_io_methods *pM
5770: 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 ethods; /* Meth
5780: 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 ods for an open
5790: 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a file */.};../*.*
57a0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 * CAPI3REF: OS I
57b0: 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 nterface File Vi
57c0: 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 rtual Methods Ob
57d0: 6a 65 63 74 20 7b 48 31 31 31 32 30 7d 20 3c 53 ject {H11120} <S
57e0: 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 45 76 65 20110>.**.** Eve
57f0: 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 ry file opened b
5800: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 y the [sqlite3_v
5810: 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 fs] xOpen method
5820: 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a populates an.**
5830: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 [sqlite3_file]
5840: 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 object (or, more
5850: 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 commonly, a sub
5860: 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 class of the.**
5870: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f [sqlite3_file] o
5880: 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f bject) with a po
5890: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 inter to an inst
58a0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a ance of this obj
58b0: 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a ect..** This obj
58c0: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 ect defines the
58d0: 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 methods used to
58e0: 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 perform various
58f0: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 operations.** ag
5900: 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 ainst the open f
5910: 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 ile represented
5920: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f by the [sqlite3_
5930: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a file] object..**
5940: 0a 2a 2a 20 49 66 20 74 68 65 20 78 4f 70 65 6e .** If the xOpen
5950: 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 method sets the
5960: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d sqlite3_file.pM
5970: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a ethods element .
5980: 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c ** to a non-NULL
5990: 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 pointer, then t
59a0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 he sqlite3_io_me
59b0: 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 thods.xClose met
59c0: 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e hod.** may be in
59d0: 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 voked even if th
59e0: 65 20 78 4f 70 65 6e 20 72 65 70 6f 72 74 65 64 e xOpen reported
59f0: 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e that it failed.
5a00: 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 The.** only wa
5a10: 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 y to prevent a c
5a20: 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f all to xClose fo
5a30: 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 llowing a failed
5a40: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 66 6f 72 xOpen.** is for
5a50: 20 74 68 65 20 78 4f 70 65 6e 20 74 6f 20 73 65 the xOpen to se
5a60: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 t the sqlite3_fi
5a70: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d le.pMethods elem
5a80: 65 6e 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a ent to NULL..**.
5a90: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 ** The flags arg
5aa0: 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d ument to xSync m
5ab0: 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 ay be one of [SQ
5ac0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c LITE_SYNC_NORMAL
5ad0: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ] or.** [SQLITE_
5ae0: 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 SYNC_FULL]. The
5af0: 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 first choice is
5b00: 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e the normal fsyn
5b10: 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f c()..** The seco
5b20: 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d nd choice is a M
5b30: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 ac OS X style fu
5b40: 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 llsync. The [SQ
5b50: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e LITE_SYNC_DATAON
5b60: 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 LY].** flag may
5b70: 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e be ORed in to in
5b80: 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 dicate that only
5b90: 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 the data of the
5ba0: 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 file.** and not
5bb0: 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 its inode needs
5bc0: 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a to be synced..*
5bd0: 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 *.** The integer
5be0: 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b values to xLock
5bf0: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 () and xUnlock()
5c00: 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c are one of.** <
5c10: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c ul>.** <li> [SQL
5c20: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a ITE_LOCK_NONE],.
5c30: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
5c40: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a LOCK_SHARED],.**
5c50: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f <li> [SQLITE_LO
5c60: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a CK_RESERVED],.**
5c70: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f <li> [SQLITE_LO
5c80: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a CK_PENDING], or.
5c90: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
5ca0: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e LOCK_EXCLUSIVE].
5cb0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f .** </ul>.** xLo
5cc0: 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 ck() increases t
5cd0: 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b he lock. xUnlock
5ce0: 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65 () decreases the
5cf0: 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 lock..** The xC
5d00: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b heckReservedLock
5d10: 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 () method checks
5d20: 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 whether any dat
5d30: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
5d40: 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 ,.** either in t
5d50: 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 his process or i
5d60: 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f n some other pro
5d70: 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 cess, is holding
5d80: 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 a RESERVED,.**
5d90: 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c PENDING, or EXCL
5da0: 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 USIVE lock on th
5db0: 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 e file. It retu
5dc0: 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 rns true.** if s
5dd0: 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 uch a lock exist
5de0: 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 s and false othe
5df0: 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 rwise..**.** The
5e00: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 xFileControl()
5e10: 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 method is a gene
5e20: 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 ric interface th
5e30: 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d at allows custom
5e40: 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e .** VFS implemen
5e50: 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 tations to direc
5e60: 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f tly control an o
5e70: 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 pen file using t
5e80: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 he.** [sqlite3_f
5e90: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 ile_control()] i
5ea0: 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 nterface. The s
5eb0: 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d econd "op" argum
5ec0: 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 ent is an.** int
5ed0: 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 eger opcode. Th
5ee0: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 e third argument
5ef0: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f is a generic po
5f00: 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 inter intended t
5f10: 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 o.** point to a
5f20: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d structure that m
5f30: 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d ay contain argum
5f40: 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e ents or space in
5f50: 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 which to.** wri
5f60: 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 te return values
5f70: 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 . Potential use
5f80: 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 s for xFileContr
5f90: 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a ol() might be.**
5fa0: 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e functions to en
5fb0: 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f able blocking lo
5fc0: 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 cks with timeout
5fd0: 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 s, to change the
5fe0: 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 .** locking stra
5ff0: 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c tegy (for exampl
6000: 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c e to use dot-fil
6010: 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 e locks), to inq
6020: 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 uire.** about th
6030: 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f e status of a lo
6040: 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 ck, or to break
6050: 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 stale locks. Th
6060: 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 e SQLite.** core
6070: 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 reserves all op
6080: 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 codes less than
6090: 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 100 for its own
60a0: 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 use..** A [SQLIT
60b0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 E_FCNTL_LOCKSTAT
60c0: 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f E | list of opco
60d0: 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 des] less than 1
60e0: 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 00 is available.
60f0: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 .** Applications
6100: 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63 that define a c
6110: 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 ustom xFileContr
6120: 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 ol method should
6130: 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 use opcodes.**
6140: 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30 greater than 100
6150: 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 to avoid confli
6160: 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 cts..**.** The x
6170: 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 SectorSize() met
6180: 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 hod returns the
6190: 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 sector size of t
61a0: 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 he.** device tha
61b0: 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 t underlies the
61c0: 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f file. The secto
61d0: 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a r size is the.**
61e0: 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 minimum write t
61f0: 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f hat can be perfo
6200: 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 rmed without dis
6210: 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 turbing.** other
6220: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 bytes in the fi
6230: 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 le. The xDevice
6240: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28 Characteristics(
6250: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 ).** method retu
6260: 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 rns a bit vector
6270: 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 describing beha
6280: 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 viors of the.**
6290: 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 underlying devic
62a0: 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a e:.**.** <ul>.**
62b0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
62c0: 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c CAP_ATOMIC].** <
62d0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
62e0: 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 P_ATOMIC512].**
62f0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
6300: 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 AP_ATOMIC1K].**
6310: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
6320: 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 AP_ATOMIC2K].**
6330: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
6340: 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 AP_ATOMIC4K].**
6350: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
6360: 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 AP_ATOMIC8K].**
6370: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
6380: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a AP_ATOMIC16K].**
6390: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
63a0: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a CAP_ATOMIC32K].*
63b0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
63c0: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a OCAP_ATOMIC64K].
63d0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
63e0: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e IOCAP_SAFE_APPEN
63f0: 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 D].** <li> [SQLI
6400: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 TE_IOCAP_SEQUENT
6410: 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a IAL].** </ul>.**
6420: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 .** The SQLITE_I
6430: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 OCAP_ATOMIC prop
6440: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 erty means that
6450: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a all writes of.**
6460: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 any size are at
6470: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 omic. The SQLIT
6480: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e E_IOCAP_ATOMICnn
6490: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e n values.** mean
64a0: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 that writes of
64b0: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 blocks that are
64c0: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a nnn bytes in siz
64d0: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 e and.** are ali
64e0: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 gned to an addre
64f0: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 ss which is an i
6500: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 nteger multiple
6510: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 of.** nnn are at
6520: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 omic. The SQLIT
6530: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 E_IOCAP_SAFE_APP
6540: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a END value means.
6550: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 ** that when dat
6560: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f a is appended to
6570: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 a file, the dat
6580: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a a is appended.**
6590: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 first then the
65a0: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 size of the file
65b0: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 is extended, ne
65c0: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a ver the other.**
65d0: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 way around. Th
65e0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 e SQLITE_IOCAP_S
65f0: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 EQUENTIAL proper
6600: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a ty means that.**
6610: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 information is
6620: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 written to disk
6630: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 in the same orde
6640: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f r as calls.** to
6650: 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a xWrite()..**.**
6660: 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75 If xRead() retu
6670: 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 rns SQLITE_IOERR
6680: 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d _SHORT_READ it m
6690: 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a ust also fill.**
66a0: 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70 in the unread p
66b0: 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 ortions of the b
66c0: 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73 uffer with zeros
66d0: 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a . A VFS that.**
66e0: 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 fails to zero-f
66f0: 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 ill short reads
6700: 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f might seem to wo
6710: 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a rk. However,.**
6720: 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f failure to zero
6730: 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 -fill short read
6740: 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c s will eventuall
6750: 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 y lead to.** dat
6760: 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e abase corruption
6770: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
6780: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d uct sqlite3_io_m
6790: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 ethods sqlite3_i
67a0: 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 o_methods;.struc
67b0: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 t sqlite3_io_met
67c0: 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 hods {. int iVe
67d0: 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 rsion;. int (*x
67e0: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 Close)(sqlite3_f
67f0: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 ile*);. int (*x
6800: 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 Read)(sqlite3_fi
6810: 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 le*, void*, int
6820: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e iAmt, sqlite3_in
6830: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e t64 iOfst);. in
6840: 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 t (*xWrite)(sqli
6850: 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 te3_file*, const
6860: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 void*, int iAmt
6870: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
6880: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a iOfst);. int (*
6890: 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 xTruncate)(sqlit
68a0: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 e3_file*, sqlite
68b0: 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 3_int64 size);.
68c0: 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 int (*xSync)(sq
68d0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 lite3_file*, int
68e0: 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 flags);. int (
68f0: 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 *xFileSize)(sqli
6900: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 te3_file*, sqlit
6910: 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 e3_int64 *pSize)
6920: 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 ;. int (*xLock)
6930: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
6940: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 int);. int (*xU
6950: 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 nlock)(sqlite3_f
6960: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e ile*, int);. in
6970: 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 t (*xCheckReserv
6980: 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f edLock)(sqlite3_
6990: 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 file*, int *pRes
69a0: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 Out);. int (*xF
69b0: 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 ileControl)(sqli
69c0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f te3_file*, int o
69d0: 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a p, void *pArg);.
69e0: 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 int (*xSectorS
69f0: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ize)(sqlite3_fil
6a00: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 e*);. int (*xDe
6a10: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 viceCharacterist
6a20: 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ics)(sqlite3_fil
6a30: 65 2a 29 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 e*);. /* Additi
6a40: 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 onal methods may
6a50: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 be added in fut
6a60: 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a ure releases */.
6a70: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 };../*.** CAPI3R
6a80: 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c EF: Standard Fil
6a90: 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 e Control Opcode
6aa0: 73 20 7b 48 31 31 33 31 30 7d 20 3c 53 33 30 38 s {H11310} <S308
6ab0: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 00>.**.** These
6ac0: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 integer constant
6ad0: 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f s are opcodes fo
6ae0: 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 r the xFileContr
6af0: 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 ol method.** of
6b00: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f the [sqlite3_io_
6b10: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 methods] object
6b20: 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c and for the [sql
6b30: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
6b40: 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 l()].** interfac
6b50: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 e..**.** The [SQ
6b60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 LITE_FCNTL_LOCKS
6b70: 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 TATE] opcode is
6b80: 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 used for debuggi
6b90: 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 ng. This.** opc
6ba0: 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 ode causes the x
6bb0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 FileControl meth
6bc0: 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 od to write the
6bd0: 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 current state of
6be0: 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e .** the lock (on
6bf0: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 e of [SQLITE_LOC
6c00: 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 K_NONE], [SQLITE
6c10: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a _LOCK_SHARED],.*
6c20: 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 * [SQLITE_LOCK_R
6c30: 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 ESERVED], [SQLIT
6c40: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c E_LOCK_PENDING],
6c50: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b or [SQLITE_LOCK
6c60: 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 _EXCLUSIVE]).**
6c70: 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 into an integer
6c80: 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72 that the pArg ar
6c90: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f gument points to
6ca0: 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 . This capabilit
6cb0: 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 y.** is used dur
6cc0: 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 ing testing and
6cd0: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 only needs to be
6ce0: 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 supported when
6cf0: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 SQLITE_TEST.** i
6d00: 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 23 64 s defined..*/.#d
6d10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
6d20: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 TL_LOCKSTATE
6d30: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 1.#define SQ
6d40: 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f LITE_GET_LOCKPRO
6d50: 58 59 46 49 4c 45 20 20 20 20 20 20 32 0a 23 64 XYFILE 2.#d
6d60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 efine SQLITE_SET
6d70: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 _LOCKPROXYFILE
6d80: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 3.#define SQ
6d90: 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 LITE_LAST_ERRNO
6da0: 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 0a 2f 4../
6db0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d *.** CAPI3REF: M
6dc0: 75 74 65 78 20 48 61 6e 64 6c 65 20 7b 48 31 37 utex Handle {H17
6dd0: 31 31 30 7d 20 3c 53 32 30 31 33 30 3e 0a 2a 2a 110} <S20130>.**
6de0: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f .** The mutex mo
6df0: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 dule within SQLi
6e00: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 te defines [sqli
6e10: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 te3_mutex] to be
6e20: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 an.** abstract
6e30: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 type for a mutex
6e40: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 object. The SQ
6e50: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 Lite core never
6e60: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 looks.** at the
6e70: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 internal represe
6e80: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 ntation of an [s
6e90: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 qlite3_mutex].
6ea0: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 It only.** deals
6eb0: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 with pointers t
6ec0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d o the [sqlite3_m
6ed0: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a utex] object..**
6ee0: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 .** Mutexes are
6ef0: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 created using [s
6f00: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c qlite3_mutex_all
6f10: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 oc()]..*/.typede
6f20: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
6f30: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d _mutex sqlite3_m
6f40: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 utex;../*.** CAP
6f50: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 I3REF: OS Interf
6f60: 61 63 65 20 4f 62 6a 65 63 74 20 7b 48 31 31 31 ace Object {H111
6f70: 34 30 7d 20 3c 53 32 30 31 30 30 3e 0a 2a 2a 0a 40} <S20100>.**.
6f80: 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f ** An instance o
6f90: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 f the sqlite3_vf
6fa0: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 s object defines
6fb0: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 the interface b
6fc0: 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 etween.** the SQ
6fd0: 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 Lite core and th
6fe0: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 e underlying ope
6ff0: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 rating system.
7000: 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 The "vfs".** in
7010: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
7020: 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f object stands fo
7030: 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 r "virtual file
7040: 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 system"..**.** T
7050: 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 he value of the
7060: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 iVersion field i
7070: 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 s initially 1 bu
7080: 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 t may be larger
7090: 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 in.** future ver
70a0: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e sions of SQLite.
70b0: 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 Additional fie
70c0: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e lds may be appen
70d0: 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f ded to this.** o
70e0: 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 bject when the i
70f0: 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 Version value is
7100: 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 increased. Not
7110: 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63 e that the struc
7120: 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 ture.** of the s
7130: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 qlite3_vfs objec
7140: 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 t changes in the
7150: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 transaction bet
7160: 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 ween.** SQLite v
7170: 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 ersion 3.5.9 and
7180: 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 3.6.0 and yet t
7190: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c he iVersion fiel
71a0: 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 d was not.** mod
71b0: 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ified..**.** The
71c0: 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 szOsFile field
71d0: 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 is the size of t
71e0: 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 he subclassed [s
71f0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 qlite3_file].**
7200: 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62 structure used b
7210: 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 y this VFS. mxP
7220: 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d athname is the m
7230: 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
7240: 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 .** a pathname i
7250: 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a n this VFS..**.*
7260: 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c * Registered sql
7270: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 ite3_vfs objects
7280: 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c are kept on a l
7290: 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 inked list forme
72a0: 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 d by.** the pNex
72b0: 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 t pointer. The
72c0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 [sqlite3_vfs_reg
72d0: 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 ister()].** and
72e0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 [sqlite3_vfs_unr
72f0: 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 egister()] inter
7300: 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 faces manage thi
7310: 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 s list.** in a t
7320: 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 hread-safe way.
7330: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 The [sqlite3_vf
7340: 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 s_find()] interf
7350: 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 ace.** searches
7360: 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 the list. Neith
7370: 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 er the applicati
7380: 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 on code nor the
7390: 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 VFS.** implement
73a0: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 ation should use
73b0: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 the pNext point
73c0: 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e er..**.** The pN
73d0: 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 ext field is the
73e0: 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 only field in t
73f0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a he sqlite3_vfs.*
7400: 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 * structure that
7410: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 SQLite will eve
7420: 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 r modify. SQLit
7430: 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 e will only acce
7440: 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 ss.** or modify
7450: 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 this field while
7460: 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 holding a parti
7470: 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 cular static mut
7480: 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 ex..** The appli
7490: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 cation should ne
74a0: 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 ver modify anyth
74b0: 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 ing within the s
74c0: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 qlite3_vfs.** ob
74d0: 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 ject once the ob
74e0: 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 ject has been re
74f0: 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 gistered..**.**
7500: 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 The zName field
7510: 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f holds the name o
7520: 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 f the VFS module
7530: 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 . The name must
7540: 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 .** be unique ac
7550: 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 ross all VFS mod
7560: 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 ules..**.** SQLi
7570: 74 65 20 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 te will guarante
7580: 65 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 e that the zFile
7590: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 name parameter t
75a0: 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 o xOpen.** is ei
75b0: 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e ther a NULL poin
75c0: 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 ter or string ob
75d0: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 tained.** from x
75e0: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 2e 20 FullPathname().
75f0: 20 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 SQLite further
7600: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a guarantees that.
7610: 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 ** the string wi
7620: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 ll be valid and
7630: 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 unchanged until
7640: 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 xClose() is.** c
7650: 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f alled. Because o
7660: 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 f the previous s
7670: 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 entence,.** the
7680: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 [sqlite3_file] c
7690: 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 an safely store
76a0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
76b0: 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 .** filename if
76c0: 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 it needs to reme
76d0: 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d mber the filenam
76e0: 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f e for some reaso
76f0: 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 n..** If the zFi
7700: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 lename parameter
7710: 20 69 73 20 78 4f 70 65 6e 20 69 73 20 61 20 4e is xOpen is a N
7720: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e ULL pointer then
7730: 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 xOpen.** must i
7740: 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 nvent its own te
7750: 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 mporary name for
7760: 20 74 68 65 20 66 69 6c 65 2e 20 20 57 68 65 6e the file. When
7770: 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 ever the .** xFi
7780: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 lename parameter
7790: 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c is NULL it will
77a0: 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 also be the cas
77b0: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c e that the.** fl
77c0: 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 ags parameter wi
77d0: 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 ll include [SQLI
77e0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e TE_OPEN_DELETEON
77f0: 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 CLOSE]..**.** Th
7800: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 e flags argument
7810: 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c to xOpen() incl
7820: 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 udes all bits se
7830: 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 t in.** the flag
7840: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 s argument to [s
7850: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
7860: 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 ]. Or if [sqlit
7870: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 e3_open()].** or
7880: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
7890: 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 ()] is used, the
78a0: 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 n flags includes
78b0: 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 at least.** [SQ
78c0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
78d0: 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f ITE] | [SQLITE_O
78e0: 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a PEN_CREATE]. .**
78f0: 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e If xOpen() open
7900: 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e s a file read-on
7910: 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 ly then it sets
7920: 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a *pOutFlags to.**
7930: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 include [SQLITE
7940: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e _OPEN_READONLY].
7950: 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 Other bits in
7960: 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 *pOutFlags may b
7970: 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c e set..**.** SQL
7980: 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 ite will also ad
7990: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c d one of the fol
79a0: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 lowing flags to
79b0: 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 the xOpen().** c
79c0: 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f all, depending o
79d0: 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 n the object bei
79e0: 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a ng opened:.**.**
79f0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b <ul>.** <li> [
7a00: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e SQLITE_OPEN_MAIN
7a10: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 _DB].** <li> [S
7a20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f QLITE_OPEN_MAIN_
7a30: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e JOURNAL].** <li>
7a40: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 [SQLITE_OPEN_T
7a50: 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 EMP_DB].** <li>
7a60: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 [SQLITE_OPEN_TE
7a70: 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c MP_JOURNAL].** <
7a80: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
7a90: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a N_TRANSIENT_DB].
7aa0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
7ab0: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c _OPEN_SUBJOURNAL
7ac0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 ].** <li> [SQLI
7ad0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a TE_OPEN_MASTER_J
7ae0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e OURNAL].** </ul>
7af0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 .**.** The file
7b00: 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 I/O implementati
7b10: 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f on can use the o
7b20: 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 bject type flags
7b30: 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 to.** change th
7b40: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 e way it deals w
7b50: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 ith files. For
7b60: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c example, an appl
7b70: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 ication.** that
7b80: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 does not care ab
7b90: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 out crash recove
7ba0: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d ry or rollback m
7bb0: 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 ight make.** the
7bc0: 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e open of a journ
7bd0: 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e al file a no-op.
7be0: 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 Writes to this
7bf0: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a journal would.*
7c00: 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 * also be no-ops
7c10: 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 , and any attemp
7c20: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f t to read the jo
7c30: 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 urnal would retu
7c40: 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 rn.** SQLITE_IOE
7c50: 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c RR. Or the impl
7c60: 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 ementation might
7c70: 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 recognize that
7c80: 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 a database.** fi
7c90: 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 le will be doing
7ca0: 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 page-aligned se
7cb0: 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 ctor reads and w
7cc0: 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f rites in a rando
7cd0: 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 m.** order and s
7ce0: 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 et up its I/O su
7cf0: 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e bsystem accordin
7d00: 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 gly..**.** SQLit
7d10: 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 e might also add
7d20: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c one of the foll
7d30: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 owing flags to t
7d40: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a he xOpen method:
7d50: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
7d60: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e li> [SQLITE_OPEN
7d70: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a _DELETEONCLOSE].
7d80: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
7d90: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a OPEN_EXCLUSIVE].
7da0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 ** </ul>.**.** T
7db0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f he [SQLITE_OPEN_
7dc0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 DELETEONCLOSE] f
7dd0: 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 lag means the fi
7de0: 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 le should be.**
7df0: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 deleted when it
7e00: 69 73 20 63 6c 6f 73 65 64 2e 20 20 54 68 65 20 is closed. The
7e10: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c [SQLITE_OPEN_DEL
7e20: 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 ETEONCLOSE].** w
7e30: 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 ill be set for T
7e40: 45 4d 50 20 20 64 61 74 61 62 61 73 65 73 2c 20 EMP databases,
7e50: 6a 6f 75 72 6e 61 6c 73 20 61 6e 64 20 66 6f 72 journals and for
7e60: 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a subjournals..**
7e70: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
7e80: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 OPEN_EXCLUSIVE]
7e90: 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 flag is always u
7ea0: 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 sed in conjuncti
7eb0: 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b on.** with the [
7ec0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 SQLITE_OPEN_CREA
7ed0: 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 TE] flag, which
7ee0: 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c are both directl
7ef0: 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 y.** analogous t
7f00: 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 o the O_EXCL and
7f10: 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f O_CREAT flags o
7f20: 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e f the POSIX open
7f30: 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 ().** API. The
7f40: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c SQLITE_OPEN_EXCL
7f50: 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e USIVE flag, when
7f60: 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 paired with the
7f70: 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e .** SQLITE_OPEN
7f80: 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 _CREATE, is used
7f90: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 to indicate tha
7fa0: 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c t file should al
7fb0: 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 ways.** be creat
7fc0: 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 ed, and that it
7fd0: 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 is an error if i
7fe0: 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 t already exists
7ff0: 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f ..** It is <i>no
8000: 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e t</i> used to in
8010: 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 dicate the file
8020: 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 should be opened
8030: 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 .** for exclusi
8040: 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a ve access..**.**
8050: 20 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 At least szOsFi
8060: 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f le bytes of memo
8070: 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 ry are allocated
8080: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f by SQLite.** to
8090: 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 hold the [sqli
80a0: 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 te3_file] struct
80b0: 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68 ure passed as th
80c0: 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d e third.** argum
80d0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 ent to xOpen. T
80e0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 he xOpen method
80f0: 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f does not have to
8100: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 .** allocate the
8110: 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 structure; it s
8120: 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 hould just fill
8130: 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 it in. Note tha
8140: 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d t.** the xOpen m
8150: 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 ethod must set t
8160: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e he sqlite3_file.
8170: 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 pMethods to eith
8180: 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 er.** a valid [s
8190: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
81a0: 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 s] object or to
81b0: 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 NULL. xOpen mus
81c0: 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 t do.** this eve
81d0: 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 n if the open fa
81e0: 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 ils. SQLite exp
81f0: 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71 ects that the sq
8200: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 lite3_file.pMeth
8210: 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 ods.** element w
8220: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 ill be valid aft
8230: 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 er xOpen returns
8240: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 regardless of t
8250: 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 he success.** or
8260: 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 failure of the
8270: 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a xOpen call..**.*
8280: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 * The flags argu
8290: 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 ment to xAccess(
82a0: 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 ) may be [SQLITE
82b0: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a _ACCESS_EXISTS].
82c0: 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 ** to test for t
82d0: 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 he existence of
82e0: 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 a file, or [SQLI
82f0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 TE_ACCESS_READWR
8300: 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 ITE] to.** test
8310: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 whether a file i
8320: 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 s readable and w
8330: 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c ritable, or [SQL
8340: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d ITE_ACCESS_READ]
8350: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 .** to test whet
8360: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 her a file is at
8370: 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e least readable.
8380: 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 The file can
8390: 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 be a.** director
83a0: 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 y..**.** SQLite
83b0: 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f will always allo
83c0: 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 cate at least mx
83d0: 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 Pathname+1 bytes
83e0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 for the.** outp
83f0: 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 ut buffer xFullP
8400: 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 athname. The ex
8410: 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 act size of the
8420: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a output buffer.**
8430: 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 is also passed
8440: 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 as a parameter t
8450: 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e o both methods.
8460: 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 If the output b
8470: 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 uffer.** is not
8480: 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 large enough, [S
8490: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 QLITE_CANTOPEN]
84a0: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e should be return
84b0: 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 ed. Since this i
84c0: 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 s.** handled as
84d0: 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 a fatal error by
84e0: 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 SQLite, vfs imp
84f0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f lementations sho
8500: 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 uld endeavor.**
8510: 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 to prevent this
8520: 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 by setting mxPat
8530: 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 hname to a suffi
8540: 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 ciently large va
8550: 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 lue..**.** The x
8560: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 Randomness(), xS
8570: 6c 65 65 70 28 29 2c 20 61 6e 64 20 78 43 75 72 leep(), and xCur
8580: 72 65 6e 74 54 69 6d 65 28 29 20 69 6e 74 65 72 rentTime() inter
8590: 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 faces.** are not
85a0: 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 strictly a part
85b0: 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 of the filesyst
85c0: 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 em, but they are
85d0: 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 .** included in
85e0: 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72 the VFS structur
85f0: 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 e for completene
8600: 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 ss..** The xRand
8610: 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f omness() functio
8620: 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 n attempts to re
8630: 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 turn nBytes byte
8640: 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 s.** of good-qua
8650: 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 lity randomness
8660: 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 into zOut. The
8670: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a return value is.
8680: 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 ** the actual nu
8690: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 mber of bytes of
86a0: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 randomness obta
86b0: 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c ined..** The xSl
86c0: 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 eep() method cau
86d0: 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 ses the calling
86e0: 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 thread to sleep
86f0: 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 for at.** least
8700: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 the number of mi
8710: 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e croseconds given
8720: 2e 20 20 54 68 65 20 78 43 75 72 72 65 6e 74 54 . The xCurrentT
8730: 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 ime().** method
8740: 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e returns a Julian
8750: 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 Day Number for
8760: 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 the current date
8770: 20 61 6e 64 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2f and time..**.*/
8780: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
8790: 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 sqlite3_vfs sqli
87a0: 74 65 33 5f 76 66 73 3b 0a 73 74 72 75 63 74 20 te3_vfs;.struct
87b0: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 sqlite3_vfs {.
87c0: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 int iVersion;
87d0: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 /* Stru
87e0: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 cture version nu
87f0: 6d 62 65 72 20 2a 2f 0a 20 20 69 6e 74 20 73 7a mber */. int sz
8800: 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 OsFile;
8810: 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 /* Size of su
8820: 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 bclassed sqlite3
8830: 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d _file */. int m
8840: 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 xPathname;
8850: 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 /* Maximum f
8860: 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e ile pathname len
8870: 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 gth */. sqlite3
8880: 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 _vfs *pNext;
8890: 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 /* Next regist
88a0: 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f ered VFS */. co
88b0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b nst char *zName;
88c0: 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f /* Name o
88d0: 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 f this virtual f
88e0: 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 ile system */.
88f0: 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 void *pAppData;
8900: 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e /* Poin
8910: 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 ter to applicati
8920: 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 on-specific data
8930: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 */. int (*xOpe
8940: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c n)(sqlite3_vfs*,
8950: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
8960: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 me, sqlite3_file
8970: 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 *,.
8980: 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 int flags, int
8990: 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 *pOutFlags);.
89a0: 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 int (*xDelete)(s
89b0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
89c0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
89d0: 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 int syncDir);.
89e0: 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 int (*xAccess)(s
89f0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
8a00: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
8a10: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a int flags, int *
8a20: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 pResOut);. int
8a30: 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 (*xFullPathname)
8a40: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
8a50: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
8a60: 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 , int nOut, char
8a70: 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 *zOut);. void
8a80: 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 *(*xDlOpen)(sqli
8a90: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
8aa0: 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 char *zFilename)
8ab0: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 ;. void (*xDlEr
8ac0: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ror)(sqlite3_vfs
8ad0: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 *, int nByte, ch
8ae0: 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 ar *zErrMsg);.
8af0: 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 void (*(*xDlSym)
8b00: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f (sqlite3_vfs*,vo
8b10: 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 id*, const char
8b20: 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 *zSymbol))(void)
8b30: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c ;. void (*xDlCl
8b40: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ose)(sqlite3_vfs
8b50: 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 *, void*);. int
8b60: 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 (*xRandomness)(
8b70: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e sqlite3_vfs*, in
8b80: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a t nByte, char *z
8b90: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 Out);. int (*xS
8ba0: 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 leep)(sqlite3_vf
8bb0: 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 s*, int microsec
8bc0: 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 onds);. int (*x
8bd0: 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c CurrentTime)(sql
8be0: 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c ite3_vfs*, doubl
8bf0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 e*);. int (*xGe
8c00: 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 tLastError)(sqli
8c10: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 te3_vfs*, int, c
8c20: 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77 har *);. /* New
8c30: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 fields may be a
8c40: 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 ppended in figur
8c50: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 e versions. The
8c60: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 iVersion. ** v
8c70: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d alue will increm
8c80: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 ent whenever thi
8c90: 73 20 68 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b s happens. */.};
8ca0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
8cb0: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 : Flags for the
8cc0: 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 xAccess VFS meth
8cd0: 6f 64 20 7b 48 31 31 31 39 30 7d 20 3c 48 31 31 od {H11190} <H11
8ce0: 31 34 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 140>.**.** These
8cf0: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e integer constan
8d00: 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 ts can be used a
8d10: 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 s the third para
8d20: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 meter to.** the
8d30: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f xAccess method o
8d40: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 f an [sqlite3_vf
8d50: 73 5d 20 6f 62 6a 65 63 74 2e 20 7b 45 4e 44 7d s] object. {END}
8d60: 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 They determine
8d70: 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 .** what kind of
8d80: 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 permissions the
8d90: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 xAccess method
8da0: 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a is looking for..
8db0: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 ** With SQLITE_A
8dc0: 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 CCESS_EXISTS, th
8dd0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 e xAccess method
8de0: 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b .** simply check
8df0: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 s whether the fi
8e00: 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 le exists..** Wi
8e10: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 th SQLITE_ACCESS
8e20: 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 _READWRITE, the
8e30: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a xAccess method.*
8e40: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 * checks whether
8e50: 20 74 68 65 20 66 69 6c 65 20 69 73 20 62 6f 74 the file is bot
8e60: 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 h readable and w
8e70: 72 69 74 61 62 6c 65 2e 0a 2a 2a 20 57 69 74 68 ritable..** With
8e80: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 SQLITE_ACCESS_R
8e90: 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 EAD, the xAccess
8ea0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b method.** check
8eb0: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 s whether the fi
8ec0: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 0a le is readable..
8ed0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
8ee0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 E_ACCESS_EXISTS
8ef0: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0.#define SQL
8f00: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 ITE_ACCESS_READW
8f10: 52 49 54 45 20 31 0a 23 64 65 66 69 6e 65 20 53 RITE 1.#define S
8f20: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
8f30: 44 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 D 2../*.**
8f40: 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 CAPI3REF: Initia
8f50: 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 lize The SQLite
8f60: 4c 69 62 72 61 72 79 20 7b 48 31 30 31 33 30 7d Library {H10130}
8f70: 20 3c 53 32 30 30 30 30 3e 3c 53 33 30 31 30 30 <S20000><S30100
8f80: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 >.**.** The sqli
8f90: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
8fa0: 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c routine initial
8fb0: 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 izes the.** SQLi
8fc0: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 te library. The
8fd0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
8fe0: 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 n() routine.** d
8ff0: 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 eallocates any r
9000: 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 esources that we
9010: 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 re allocated by
9020: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
9030: 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 ze()..**.** A ca
9040: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e ll to sqlite3_in
9050: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e itialize() is an
9060: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c "effective" cal
9070: 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 l if it is.** th
9080: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c e first time sql
9090: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
90a0: 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 ) is invoked dur
90b0: 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 ing the lifetime
90c0: 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 of.** the proce
90d0: 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 ss, or if it is
90e0: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 the first time s
90f0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
9100: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a e() is invoked.*
9110: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 * following a ca
9120: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 ll to sqlite3_sh
9130: 75 74 64 6f 77 6e 28 29 2e 20 20 4f 6e 6c 79 20 utdown(). Only
9140: 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c an effective cal
9150: 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f l.** of sqlite3_
9160: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 initialize() doe
9170: 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 s any initializa
9180: 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 tion. All other
9190: 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 calls.** are ha
91a0: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 0a 2a rmless no-ops..*
91b0: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 *.** A call to s
91c0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
91d0: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 ) is an "effecti
91e0: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 ve" call if it i
91f0: 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 s the first.** c
9200: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 all to sqlite3_s
9210: 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 hutdown() since
9220: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 the last sqlite3
9230: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 _initialize().
9240: 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 Only.** an effec
9250: 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c tive call to sql
9260: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 ite3_shutdown()
9270: 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 does any deiniti
9280: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c alization..** Al
9290: 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 20 74 6f l other calls to
92a0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
92b0: 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 n() are harmless
92c0: 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 41 no-ops..**.** A
92d0: 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 mong other thing
92e0: 73 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 s, sqlite3_initi
92f0: 61 6c 69 7a 65 28 29 20 73 68 61 6c 6c 20 69 6e alize() shall in
9300: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f voke.** sqlite3_
9310: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 os_init(). Simi
9320: 6c 61 72 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 larly, sqlite3_s
9330: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 73 68 61 hutdown().** sha
9340: 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 ll invoke sqlite
9350: 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 3_os_end()..**.*
9360: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e * The sqlite3_in
9370: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 itialize() routi
9380: 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 ne returns [SQLI
9390: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 TE_OK] on succes
93a0: 73 2e 0a 2a 2a 20 49 66 20 66 6f 72 20 73 6f 6d s..** If for som
93b0: 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 e reason, sqlite
93c0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 3_initialize() i
93d0: 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 s unable to init
93e0: 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 ialize.** the li
93f0: 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69 brary (perhaps i
9400: 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 t is unable to a
9410: 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 llocate a needed
9420: 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a resource such.*
9430: 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 * as a mutex) it
9440: 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 returns an [err
9450: 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 or code] other t
9460: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e han [SQLITE_OK].
9470: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
9480: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
9490: 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 routine is calle
94a0: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 d internally by
94b0: 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 many other.** SQ
94c0: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 Lite interfaces
94d0: 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 so that an appli
94e0: 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 cation usually d
94f0: 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a oes not need to.
9500: 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 ** invoke sqlite
9510: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 3_initialize() d
9520: 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 irectly. For ex
9530: 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f ample, [sqlite3_
9540: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 open()].** calls
9550: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
9560: 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c ize() so the SQL
9570: 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c ite library will
9580: 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c be automaticall
9590: 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 y.** initialized
95a0: 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f when [sqlite3_o
95b0: 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 pen()] is called
95c0: 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 if it has not b
95d0: 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a e initialized.**
95e0: 20 61 6c 72 65 61 64 79 2e 20 20 48 6f 77 65 76 already. Howev
95f0: 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 er, if SQLite is
9600: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 compiled with t
9610: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f he [SQLITE_OMIT_
9620: 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d AUTOINIT].** com
9630: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
9640: 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d , then the autom
9650: 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 atic calls to sq
9660: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
9670: 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 ().** are omitte
9680: 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 d and the applic
9690: 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 ation must call
96a0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
96b0: 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a ze() directly.**
96c0: 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 prior to using
96d0: 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 any other SQLite
96e0: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 interface. For
96f0: 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 maximum portabi
9700: 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 lity,.** it is r
9710: 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 ecommended that
9720: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 applications alw
9730: 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 ays invoke sqlit
9740: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a e3_initialize().
9750: 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f ** directly prio
9760: 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f r to using any o
9770: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 ther SQLite inte
9780: 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 rface. Future r
9790: 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 eleases.** of SQ
97a0: 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 Lite may require
97b0: 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 this. In other
97c0: 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 words, the beha
97d0: 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a vior exhibited.*
97e0: 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 * when SQLite is
97f0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b compiled with [
9800: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f SQLITE_OMIT_AUTO
9810: 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f INIT] might beco
9820: 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c me the.** defaul
9830: 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f t behavior in so
9840: 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 me future releas
9850: 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a e of SQLite..**.
9860: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f ** The sqlite3_o
9870: 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 s_init() routine
9880: 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d does operating-
9890: 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a system specific.
98a0: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f ** initializatio
98b0: 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 n of the SQLite
98c0: 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 library. The sq
98d0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a lite3_os_end().*
98e0: 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 * routine undoes
98f0: 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 the effect of s
9900: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
9910: 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 . Typical tasks
9920: 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 .** performed by
9930: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
9940: 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 include allocati
9950: 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 on or deallocati
9960: 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 on.** of static
9970: 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 resources, initi
9980: 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f alization of glo
9990: 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a bal variables,.*
99a0: 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 * setting up a d
99b0: 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f efault [sqlite3_
99c0: 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 vfs] module, or
99d0: 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 setting up.** a
99e0: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 default configur
99f0: 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c ation using [sql
9a00: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a ite3_config()]..
9a10: 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 **.** The applic
9a20: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 ation should nev
9a30: 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 er invoke either
9a40: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
9a50: 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 ().** or sqlite3
9a60: 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 _os_end() direct
9a70: 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 ly. The applica
9a80: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 tion should only
9a90: 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 invoke.** sqlit
9aa0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
9ab0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 and sqlite3_shut
9ac0: 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c down(). The sql
9ad0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a ite3_os_init().*
9ae0: 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 * interface is c
9af0: 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 alled automatica
9b00: 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 lly by sqlite3_i
9b10: 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a nitialize() and.
9b20: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e ** sqlite3_os_en
9b30: 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 d() is called by
9b40: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
9b50: 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 n(). Appropriat
9b60: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 e.** implementat
9b70: 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 ions for sqlite3
9b80: 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 _os_init() and s
9b90: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a qlite3_os_end().
9ba0: 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 ** are built int
9bb0: 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 o SQLite when it
9bc0: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 is compiled for
9bd0: 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 Unix, Windows,
9be0: 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e or OS/2..** When
9bf0: 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 [custom builds
9c00: 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 | built for othe
9c10: 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 r platforms].**
9c20: 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 (using the [SQLI
9c30: 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 TE_OS_OTHER=1] c
9c40: 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f ompile-time.** o
9c50: 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 ption) the appli
9c60: 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 cation must supp
9c70: 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d ly a suitable im
9c80: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 plementation for
9c90: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 .** sqlite3_os_i
9ca0: 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 nit() and sqlite
9cb0: 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 3_os_end(). An
9cc0: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 application-supp
9cd0: 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e lied.** implemen
9ce0: 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 tation of sqlite
9cf0: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 3_os_init() or s
9d00: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a qlite3_os_end().
9d10: 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b ** must return [
9d20: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 SQLITE_OK] on su
9d30: 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f ccess and some o
9d40: 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 ther [error code
9d50: 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 ] upon.** failur
9d60: 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 e..*/.SQLITE_API
9d70: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 int sqlite3_ini
9d80: 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 53 tialize(void);.S
9d90: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
9da0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 lite3_shutdown(v
9db0: 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 oid);.SQLITE_API
9dc0: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f int sqlite3_os_
9dd0: 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53 51 4c 49 init(void);.SQLI
9de0: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
9df0: 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b e3_os_end(void);
9e00: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
9e10: 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 : Configuring Th
9e20: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 e SQLite Library
9e30: 20 7b 48 31 34 31 30 30 7d 20 3c 53 32 30 30 30 {H14100} <S2000
9e40: 30 3e 3c 53 33 30 32 30 30 3e 0a 2a 2a 20 45 58 0><S30200>.** EX
9e50: 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a PERIMENTAL.**.**
9e60: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e The sqlite3_con
9e70: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 fig() interface
9e80: 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 is used to make
9e90: 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 global configura
9ea0: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 tion.** changes
9eb0: 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 to SQLite in ord
9ec0: 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 er to tune SQLit
9ed0: 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 e to the specifi
9ee0: 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 c needs of.** th
9ef0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 e application.
9f00: 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 The default conf
9f10: 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 iguration is rec
9f20: 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 ommended for mos
9f30: 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e t.** application
9f40: 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f s and so this ro
9f50: 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 utine is usually
9f60: 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 not necessary.
9f70: 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 It is.** provid
9f80: 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 ed to support ra
9f90: 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 re applications
9fa0: 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 with unusual nee
9fb0: 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ds..**.** The sq
9fc0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 lite3_config() i
9fd0: 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 nterface is not
9fe0: 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 threadsafe. The
9ff0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 application.**
a000: 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 must insure that
a010: 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 no other SQLite
a020: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
a030: 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 invoked by other
a040: 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c .** threads whil
a050: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 e sqlite3_config
a060: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 () is running.
a070: 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c Furthermore, sql
a080: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a ite3_config().**
a090: 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 may only be inv
a0a0: 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 oked prior to li
a0b0: 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 brary initializa
a0c0: 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 tion using.** [s
a0d0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
a0e0: 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 e()] or after sh
a0f0: 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 utdown by [sqlit
a100: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a e3_shutdown()]..
a110: 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 ** Note, however
a120: 2c 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 63 , that sqlite3_c
a130: 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 onfig() can be c
a140: 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 alled as part of
a150: 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e the.** implemen
a160: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 tation of an app
a170: 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
a180: 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 [sqlite3_os_ini
a190: 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 t()]..**.** The
a1a0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
a1b0: 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 o sqlite3_config
a1c0: 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 () is an integer
a1d0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 .** [SQLITE_CONF
a1e0: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 IG_SINGLETHREAD
a1f0: 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 | configuration
a200: 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 option] that det
a210: 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 ermines.** what
a220: 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 property of SQLi
a230: 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 te is to be conf
a240: 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 igured. Subsequ
a250: 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a ent arguments.**
a260: 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 vary depending
a270: 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 on the [SQLITE_C
a280: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 ONFIG_SINGLETHRE
a290: 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 AD | configurati
a2a0: 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e on option].** in
a2b0: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
a2c0: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 ent..**.** When
a2d0: 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 a configuration
a2e0: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 option is set, s
a2f0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
a300: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
a310: 4f 4b 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6f OK]..** If the o
a320: 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e ption is unknown
a330: 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e or SQLite is un
a340: 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 able to set the
a350: 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 option.** then t
a360: 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 his routine retu
a370: 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b rns a non-zero [
a380: 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a error code]..**.
a390: 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
a3a0: 0a 2a 2a 20 5b 48 31 34 31 30 33 5d 20 5b 48 31 .** [H14103] [H1
a3b0: 34 31 30 36 5d 20 5b 48 31 34 31 32 30 5d 20 5b 4106] [H14120] [
a3c0: 48 31 34 31 32 33 5d 20 5b 48 31 34 31 32 36 5d H14123] [H14126]
a3d0: 20 5b 48 31 34 31 32 39 5d 20 5b 48 31 34 31 33 [H14129] [H1413
a3e0: 32 5d 20 5b 48 31 34 31 33 35 5d 0a 2a 2a 20 5b 2] [H14135].** [
a3f0: 48 31 34 31 33 38 5d 20 5b 48 31 34 31 34 31 5d H14138] [H14141]
a400: 20 5b 48 31 34 31 34 34 5d 20 5b 48 31 34 31 34 [H14144] [H1414
a410: 37 5d 20 5b 48 31 34 31 35 30 5d 20 5b 48 31 34 7] [H14150] [H14
a420: 31 35 33 5d 20 5b 48 31 34 31 35 36 5d 20 5b 48 153] [H14156] [H
a430: 31 34 31 35 39 5d 0a 2a 2a 20 5b 48 31 34 31 36 14159].** [H1416
a440: 32 5d 20 5b 48 31 34 31 36 35 5d 20 5b 48 31 34 2] [H14165] [H14
a450: 31 36 38 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 168].*/.SQLITE_A
a460: 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 PI SQLITE_EXPERI
a470: 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 MENTAL int sqlit
a480: 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e e3_config(int, .
a490: 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ..);../*.** CAPI
a4a0: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 3REF: Configure
a4b0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
a4c0: 69 6f 6e 73 20 20 7b 48 31 34 32 30 30 7d 20 3c ions {H14200} <
a4d0: 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52 S20000>.** EXPER
a4e0: 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 IMENTAL.**.** Th
a4f0: 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e e sqlite3_db_con
a500: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 fig() interface
a510: 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 is used to make
a520: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a configuration.**
a530: 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 changes to a [d
a540: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
a550: 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 on]. The interf
a560: 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 ace is similar t
a570: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f o.** [sqlite3_co
a580: 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 nfig()] except t
a590: 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 hat the changes
a5a0: 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c apply to a singl
a5b0: 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 e.** [database c
a5c0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 onnection] (spec
a5d0: 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 ified in the fir
a5e0: 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 20 20 54 st argument). T
a5f0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 64 62 he.** sqlite3_db
a600: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 _config() interf
a610: 61 63 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 ace can only be
a620: 75 73 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 used immediately
a630: 20 61 66 74 65 72 0a 2a 2a 20 74 68 65 20 64 61 after.** the da
a640: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
a650: 6e 20 69 73 20 63 72 65 61 74 65 64 20 75 73 69 n is created usi
a660: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ng [sqlite3_open
a670: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
a680: 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b _open16()], or [
a690: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
a6a0: 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 )]. .**.** The
a6b0: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
a6c0: 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f to sqlite3_db_co
a6d0: 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 nfig(D,V,...) i
a6e0: 73 20 74 68 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 s the.** configu
a6f0: 72 61 74 69 6f 6e 20 76 65 72 62 20 2d 20 61 6e ration verb - an
a700: 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 integer code th
a710: 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 at indicates wha
a720: 74 0a 2a 2a 20 61 73 70 65 63 74 20 6f 66 20 74 t.** aspect of t
a730: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
a740: 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e nection] is bein
a750: 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a g configured..**
a760: 20 54 68 65 20 6f 6e 6c 79 20 63 68 6f 69 63 65 The only choice
a770: 20 66 6f 72 20 74 68 69 73 20 76 61 6c 75 65 20 for this value
a780: 69 73 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e is [SQLITE_DBCON
a790: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a FIG_LOOKASIDE]..
a7a0: 2a 2a 20 4e 65 77 20 76 65 72 62 73 20 61 72 65 ** New verbs are
a7b0: 20 6c 69 6b 65 6c 79 20 74 6f 20 62 65 20 61 64 likely to be ad
a7c0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 ded in future re
a7d0: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 leases of SQLite
a7e0: 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 ..** Additional
a7f0: 61 72 67 75 6d 65 6e 74 73 20 64 65 70 65 6e 64 arguments depend
a800: 20 6f 6e 20 74 68 65 20 76 65 72 62 2e 0a 2a 2a on the verb..**
a810: 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
a820: 3a 0a 2a 2a 20 5b 48 31 34 32 30 33 5d 20 5b 48 :.** [H14203] [H
a830: 31 34 32 30 36 5d 20 5b 48 31 34 32 30 39 5d 20 14206] [H14209]
a840: 5b 48 31 34 32 31 32 5d 20 5b 48 31 34 32 31 35 [H14212] [H14215
a850: 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
a860: 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e SQLITE_EXPERIMEN
a870: 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f TAL int sqlite3_
a880: 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 db_config(sqlite
a890: 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3*, int op, ...)
a8a0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
a8b0: 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 F: Memory Alloca
a8c0: 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b 48 tion Routines {H
a8d0: 31 30 31 35 35 7d 20 3c 53 32 30 31 32 30 3e 0a 10155} <S20120>.
a8e0: 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a ** EXPERIMENTAL.
a8f0: 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 **.** An instanc
a900: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 e of this object
a910: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 defines the int
a920: 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 erface between S
a930: 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 QLite.** and low
a940: 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c -level memory al
a950: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 location routine
a960: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 s..**.** This ob
a970: 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 ject is used in
a980: 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 only one place i
a990: 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 n the SQLite int
a9a0: 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 erface..** A poi
a9b0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 nter to an insta
a9c0: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 nce of this obje
a9d0: 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 ct is the argume
a9e0: 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 nt to.** [sqlite
a9f0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 3_config()] when
aa00: 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 the configurati
aa10: 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 on option is.**
aa20: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
aa30: 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 ALLOC] or [SQLIT
aa40: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c E_CONFIG_GETMALL
aa50: 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 OC]. .** By cre
aa60: 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 ating an instanc
aa70: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 e of this object
aa80: 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 .** and passing
aa90: 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 it to [sqlite3_c
aaa0: 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 onfig]([SQLITE_C
aab0: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a ONFIG_MALLOC]).*
aac0: 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 * during configu
aad0: 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 ration, an appli
aae0: 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 cation can speci
aaf0: 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 fy an alternativ
ab00: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f e.** memory allo
ab10: 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d cation subsystem
ab20: 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 for SQLite to u
ab30: 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 se for all of it
ab40: 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d s.** dynamic mem
ab50: 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a ory needs..**.**
ab60: 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 Note that SQLit
ab70: 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 e comes with sev
ab80: 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d eral [built-in m
ab90: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 emory allocators
aba0: 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 ].** that are pe
abb0: 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 rfectly adequate
abc0: 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 for the overwhe
abd0: 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f lming majority o
abe0: 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a f applications.*
abf0: 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 * and that this
ac00: 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 object is only u
ac10: 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 seful to a tiny
ac20: 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c minority of appl
ac30: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 ications.** with
ac40: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d specialized mem
ac50: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
ac60: 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 equirements. Th
ac70: 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 is object is.**
ac80: 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 also used during
ac90: 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 testing of SQLi
aca0: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 te in order to s
acb0: 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e pecify an altern
acc0: 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 ative.** memory
acd0: 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 allocator that s
ace0: 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 imulates memory
acf0: 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f out-of-memory co
ad00: 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f nditions in.** o
ad10: 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 rder to verify t
ad20: 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 hat SQLite recov
ad30: 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 ers gracefully f
ad40: 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 rom such.** cond
ad50: 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 itions..**.** Th
ad60: 65 20 78 4d 61 6c 6c 6f 63 20 61 6e 64 20 78 46 e xMalloc and xF
ad70: 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 ree methods must
ad80: 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a work like the.*
ad90: 2a 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 * malloc() and f
ada0: 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 ree() functions
adb0: 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 from the standar
adc0: 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 d C library..**
add0: 54 68 65 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 The xRealloc met
ade0: 68 6f 64 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 hod must work li
adf0: 6b 65 20 72 65 61 6c 6c 6f 63 28 29 20 66 72 6f ke realloc() fro
ae00: 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 m the standard C
ae10: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 77 69 74 68 library.** with
ae20: 20 74 68 65 20 65 78 63 65 70 74 69 6f 6e 20 74 the exception t
ae30: 68 61 74 20 69 66 20 74 68 65 20 73 65 63 6f 6e hat if the secon
ae40: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 52 d argument to xR
ae50: 65 61 6c 6c 6f 63 20 69 73 20 7a 65 72 6f 2c 0a ealloc is zero,.
ae60: 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 6d 75 73 74 ** xRealloc must
ae70: 20 62 65 20 61 20 6e 6f 2d 6f 70 20 2d 20 69 74 be a no-op - it
ae80: 20 6d 75 73 74 20 6e 6f 74 20 70 65 72 66 6f 72 must not perfor
ae90: 6d 20 61 6e 79 20 61 6c 6c 6f 63 61 74 69 6f 6e m any allocation
aea0: 20 6f 72 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 or.** deallocat
aeb0: 69 6f 6e 2e 20 20 53 51 4c 69 74 65 20 67 75 61 ion. SQLite gua
aec0: 72 61 6e 74 65 65 64 73 20 74 68 61 74 20 74 68 ranteeds that th
aed0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
aee0: 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 t to.** xRealloc
aef0: 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c is always a val
af00: 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 ue returned by a
af10: 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 prior call to x
af20: 52 6f 75 6e 64 75 70 2e 0a 2a 2a 20 41 6e 64 20 Roundup..** And
af30: 73 6f 20 69 6e 20 63 61 73 65 73 20 77 68 65 72 so in cases wher
af40: 65 20 78 52 6f 75 6e 64 75 70 20 61 6c 77 61 79 e xRoundup alway
af50: 73 20 72 65 74 75 72 6e 73 20 61 20 70 6f 73 69 s returns a posi
af60: 74 69 76 65 20 6e 75 6d 62 65 72 2c 0a 2a 2a 20 tive number,.**
af70: 78 52 65 61 6c 6c 6f 63 20 63 61 6e 20 70 65 72 xRealloc can per
af80: 66 6f 72 6d 20 65 78 61 63 74 6c 79 20 61 73 20 form exactly as
af90: 74 68 65 20 73 74 61 6e 64 61 72 64 20 6c 69 62 the standard lib
afa0: 72 61 72 79 20 72 65 61 6c 6c 6f 63 28 29 20 61 rary realloc() a
afb0: 6e 64 0a 2a 2a 20 73 74 69 6c 6c 20 62 65 20 69 nd.** still be i
afc0: 6e 20 63 6f 6d 70 6c 69 61 6e 63 65 20 77 69 74 n compliance wit
afd0: 68 20 74 68 69 73 20 73 70 65 63 69 66 69 63 61 h this specifica
afe0: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a tion..**.** xSiz
aff0: 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 e should return
b000: 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 the allocated si
b010: 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 ze of a memory a
b020: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 llocation.** pre
b030: 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 viously obtained
b040: 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 from xMalloc or
b050: 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 xRealloc. The
b060: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a allocated size.*
b070: 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c * is always at l
b080: 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74 east as big as t
b090: 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a he requested siz
b0a0: 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 e but may be lar
b0b0: 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ger..**.** The x
b0c0: 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 Roundup method r
b0d0: 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c eturns what woul
b0e0: 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 d be the allocat
b0f0: 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 ed size of.** a
b100: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
b110: 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 n given a partic
b120: 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73 ular requested s
b130: 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 ize. Most memor
b140: 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 y.** allocators
b150: 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 round up memory
b160: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c allocations at l
b170: 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 east to the next
b180: 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 multiple.** of
b190: 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 8. Some allocat
b1a0: 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 ors round up to
b1b0: 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c a larger multipl
b1c0: 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 e or to a power
b1d0: 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d of 2..** Every m
b1e0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
b1f0: 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 request coming
b200: 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 in through [sqli
b210: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a te3_malloc()].**
b220: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 or [sqlite3_rea
b230: 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 lloc()] first ca
b240: 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 lls xRoundup. I
b250: 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 f xRoundup retur
b260: 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 ns 0, .** that c
b270: 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 auses the corres
b280: 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 ponding memory a
b290: 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 llocation to fai
b2a0: 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e l..**.** The xIn
b2b0: 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 it method initia
b2c0: 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 lizes the memory
b2d0: 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f allocator. (Fo
b2e0: 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 r example,.** it
b2f0: 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 might allocate
b300: 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 any require mute
b310: 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a xes or initializ
b320: 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a e internal data.
b330: 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 ** structures.
b340: 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 The xShutdown me
b350: 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 thod is invoked
b360: 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a (indirectly) by.
b370: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 ** [sqlite3_shut
b380: 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 down()] and shou
b390: 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e ld deallocate an
b3a0: 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 y resources acqu
b3b0: 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 ired.** by xInit
b3c0: 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20 . The pAppData
b3d0: 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 pointer is used
b3e0: 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 as the only para
b3f0: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 meter to.** xIni
b400: 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e t and xShutdown.
b410: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f .**.** SQLite ho
b420: 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f lds the [SQLITE_
b430: 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 MUTEX_STATIC_MAS
b440: 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 TER] mutex when
b450: 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 it invokes.** th
b460: 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 e xInit method,
b470: 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 so the xInit met
b480: 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 hod need not be
b490: 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 threadsafe. The
b4a0: 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 .** xShutdown me
b4b0: 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c thod is only cal
b4c0: 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 led from [sqlite
b4d0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 3_shutdown()] so
b4e0: 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 it does.** not
b4f0: 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 need to be threa
b500: 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 dsafe either. F
b510: 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 or all other met
b520: 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 hods, SQLite.**
b530: 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 holds the [SQLIT
b540: 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d E_MUTEX_STATIC_M
b550: 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e EM] mutex as lon
b560: 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c g as the.** [SQL
b570: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 ITE_CONFIG_MEMST
b580: 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 ATUS] configurat
b590: 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 ion option is tu
b5a0: 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a rned on (which.*
b5b0: 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75 * it is by defau
b5c0: 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d lt) and so the m
b5d0: 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d ethods are autom
b5e0: 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 atically seriali
b5f0: 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c zed..** However,
b600: 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 if [SQLITE_CONF
b610: 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 IG_MEMSTATUS] is
b620: 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 disabled, then
b630: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 the other.** met
b640: 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 hods must be thr
b650: 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 eadsafe or else
b660: 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 make their own a
b670: 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a rrangements for.
b680: 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e ** serialization
b690: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 ..**.** SQLite w
b6a0: 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 ill never invoke
b6b0: 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 xInit() more th
b6c0: 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 an once without
b6d0: 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a an intervening.*
b6e0: 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 * call to xShutd
b6f0: 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 own()..*/.typede
b700: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
b710: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c _mem_methods sql
b720: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
b730: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 ;.struct sqlite3
b740: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 _mem_methods {.
b750: 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 void *(*xMalloc
b760: 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 )(int);
b770: 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 /* Memory alloca
b780: 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f tion function */
b790: 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 . void (*xFree)
b7a0: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 (void*);
b7b0: 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f /* Free a prio
b7c0: 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a r allocation */.
b7d0: 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c void *(*xReall
b7e0: 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 oc)(void*,int);
b7f0: 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c /* Resize an al
b800: 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e location */. in
b810: 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a t (*xSize)(void*
b820: 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 ); /*
b830: 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 Return the size
b840: 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e of an allocation
b850: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 */. int (*xRou
b860: 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 ndup)(int);
b870: 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 /* Round up
b880: 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f request size to
b890: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 allocation size
b8a0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 */. int (*xIni
b8b0: 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 t)(void*);
b8c0: 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 /* Initiali
b8d0: 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c ze the memory al
b8e0: 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 locator */. voi
b8f0: 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 d (*xShutdown)(v
b900: 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 oid*); /* D
b910: 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 einitialize the
b920: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
b930: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 */. void *pApp
b940: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 Data;
b950: 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 /* Argument
b960: 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 to xInit() and
b970: 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d xShutdown() */.}
b980: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
b990: 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e F: Configuration
b9a0: 20 4f 70 74 69 6f 6e 73 20 7b 48 31 30 31 36 30 Options {H10160
b9b0: 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58 } <S20000>.** EX
b9c0: 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a PERIMENTAL.**.**
b9d0: 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 These constants
b9e0: 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 are the availab
b9f0: 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 le integer confi
ba00: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 guration options
ba10: 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 that.** can be
ba20: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 passed as the fi
ba30: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
ba40: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e the [sqlite3_con
ba50: 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 fig()] interface
ba60: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 ..**.** New conf
ba70: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
ba80: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 s may be added i
ba90: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
baa0: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 s of SQLite..**
bab0: 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 Existing configu
bac0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d ration options m
bad0: 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 ight be disconti
bae0: 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 nued. Applicati
baf0: 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 ons.** should ch
bb00: 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 eck the return c
bb10: 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ode from [sqlite
bb20: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 3_config()] to m
bb30: 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a ake sure that.**
bb40: 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 the call worked
bb50: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f . The [sqlite3_
bb60: 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 config()] interf
bb70: 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ace will return
bb80: 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 a.** non-zero [e
bb90: 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 rror code] if a
bba0: 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 discontinued or
bbb0: 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 unsupported conf
bbc0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
bbd0: 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a .** is invoked..
bbe0: 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 **.** <dl>.** <d
bbf0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
bc00: 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 SINGLETHREAD</dt
bc10: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 >.** <dd>There a
bc20: 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 re no arguments
bc30: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 to this option.
bc40: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 This option dis
bc50: 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 ables.** all mut
bc60: 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 exing and puts S
bc70: 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 QLite into a mod
bc80: 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f e where it can o
bc90: 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 nly be used.** b
bca0: 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 y a single threa
bcb0: 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 d.</dd>.**.** <d
bcc0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
bcd0: 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e MULTITHREAD</dt>
bce0: 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 .** <dd>There ar
bcf0: 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 e no arguments t
bd00: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 o this option.
bd10: 54 68 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 This option disa
bd20: 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 bles.** mutexing
bd30: 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f on [database co
bd40: 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 nnection] and [p
bd50: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
bd60: 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 t] objects..** T
bd70: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 he application i
bd80: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f s responsible fo
bd90: 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 r serializing ac
bda0: 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 cess to.** [data
bdb0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
bdc0: 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 ] and [prepared
bdd0: 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 statements]. Bu
bde0: 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a t other mutexes.
bdf0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 ** are enabled s
be00: 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 o that SQLite wi
be10: 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 ll be safe to us
be20: 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 e in a multi-thr
be30: 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e eaded.** environ
be40: 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 ment as long as
be50: 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 no two threads a
be60: 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 ttempt to use th
be70: 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 e same.** [datab
be80: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
be90: 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 at the same time
bea0: 2e 20 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 . See the [thre
beb0: 61 64 69 6e 67 20 6d 6f 64 65 5d 0a 2a 2a 20 64 ading mode].** d
bec0: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 ocumentation for
bed0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f additional info
bee0: 72 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a rmation.</dd>.**
bef0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
bf00: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 ONFIG_SERIALIZED
bf10: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
bf20: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 re are no argume
bf30: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 nts to this opti
bf40: 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e on. This option
bf50: 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 enables.** all
bf60: 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e mutexes includin
bf70: 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a g the recursive.
bf80: 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 ** mutexes on [d
bf90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
bfa0: 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 on] and [prepare
bfb0: 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a d statement] obj
bfc0: 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 ects..** In this
bfd0: 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 mode (which is
bfe0: 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e the default when
bff0: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
c000: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c led with.** [SQL
c010: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 ITE_THREADSAFE=1
c020: 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 ]) the SQLite li
c030: 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c brary will itsel
c040: 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 f serialize acce
c050: 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 ss.** to [databa
c060: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 se connections]
c070: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 and [prepared st
c080: 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 atements] so tha
c090: 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 t the.** applica
c0a0: 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 tion is free to
c0b0: 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 use the same [da
c0c0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
c0d0: 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d n] or the.** sam
c0e0: 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
c0f0: 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 ement] in differ
c100: 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 ent threads at t
c110: 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a he same time..**
c120: 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 See the [thread
c130: 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 ing mode] docume
c140: 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 ntation for addi
c150: 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 tional informati
c160: 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c on.</dd>.**.** <
c170: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
c180: 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 _MALLOC</dt>.**
c190: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 <dd>This option
c1a0: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
c1b0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
c1c0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
c1d0: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 .** instance of
c1e0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d the [sqlite3_mem
c1f0: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 _methods] struct
c200: 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 ure. The argume
c210: 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 nt specifies.**
c220: 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d alternative low-
c230: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c level memory all
c240: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 ocation routines
c250: 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 to be used in p
c260: 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d lace of.** the m
c270: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
c280: 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 routines built
c290: 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64 into SQLite.</dd
c2a0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
c2b0: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c TE_CONFIG_GETMAL
c2c0: 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e LOC</dt>.** <dd>
c2d0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
c2e0: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
c2f0: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 ent which is a p
c300: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 ointer to an.**
c310: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 instance of the
c320: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 [sqlite3_mem_met
c330: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e hods] structure.
c340: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d The [sqlite3_m
c350: 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 em_methods].** s
c360: 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c tructure is fill
c370: 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 ed with the curr
c380: 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 ently defined me
c390: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
c3a0: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 routines..** Thi
c3b0: 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 s option can be
c3c0: 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 used to overload
c3d0: 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d the default mem
c3e0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a ory allocation.*
c3f0: 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 * routines with
c400: 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73 a wrapper that s
c410: 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 imulations memor
c420: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 y allocation fai
c430: 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b lure or.** track
c440: 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 s memory usage,
c450: 66 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 for example.</dd
c460: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
c470: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 TE_CONFIG_MEMSTA
c480: 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e TUS</dt>.** <dd>
c490: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
c4a0: 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e s single argumen
c4b0: 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 t of type int, i
c4c0: 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 nterpreted as a
c4d0: 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 .** boolean, whi
c4e0: 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 ch enables or di
c4f0: 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 sables the colle
c500: 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 ction of memory
c510: 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 allocation .** s
c520: 74 61 74 69 73 74 69 63 73 2e 20 57 68 65 6e 20 tatistics. When
c530: 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f disabled, the fo
c540: 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 llowing SQLite i
c550: 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 nterfaces become
c560: 20 0a 2a 2a 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 .** non-operati
c570: 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a onal:.** <ul>.
c580: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 ** <li> [sqlit
c590: 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 e3_memory_used()
c5a0: 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c ].** <li> [sql
c5b0: 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 ite3_memory_high
c5c0: 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c water()].** <l
c5d0: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 i> [sqlite3_soft
c5e0: 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a _heap_limit()].*
c5f0: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 * <li> [sqlite
c600: 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 3_status()].**
c610: 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a </ul>.** </dd>.
c620: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
c630: 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c _CONFIG_SCRATCH<
c640: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 /dt>.** <dd>This
c650: 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 option specifie
c660: 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 s a static memor
c670: 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 y buffer that SQ
c680: 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 Lite can use for
c690: 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f .** scratch memo
c6a0: 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 ry. There are t
c6b0: 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 hree arguments:
c6c0: 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d A pointer an 8-
c6d0: 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 byte.** aligned
c6e0: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 memory buffer fr
c6f0: 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72 om which the scr
c700: 61 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 ach allocations
c710: 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e will be.** drawn
c720: 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 , the size of ea
c730: 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 ch scratch alloc
c740: 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 ation (sz),.** a
c750: 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e nd the maximum n
c760: 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 umber of scratch
c770: 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 allocations (N)
c780: 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 . The sz.** arg
c790: 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 ument must be a
c7a0: 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 20 multiple of 16.
c7b0: 54 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 The sz parameter
c7c0: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 66 65 77 should be a few
c7d0: 20 62 79 74 65 73 0a 2a 2a 20 6c 61 72 67 65 72 bytes.** larger
c7e0: 20 74 68 61 6e 20 74 68 65 20 61 63 74 75 61 6c than the actual
c7f0: 20 73 63 72 61 74 63 68 20 73 70 61 63 65 20 72 scratch space r
c800: 65 71 75 69 72 65 64 20 64 75 65 20 74 6f 20 69 equired due to i
c810: 6e 74 65 72 6e 61 6c 20 6f 76 65 72 68 65 61 64 nternal overhead
c820: 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 ..** The first a
c830: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 rgument should p
c840: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 ointer to an 8-b
c850: 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 yte aligned buff
c860: 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 er.** of at leas
c870: 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 t sz*N bytes of
c880: 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 memory..** SQLit
c890: 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f e will use no mo
c8a0: 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 re than one scra
c8b0: 74 63 68 20 62 75 66 66 65 72 20 61 74 20 6f 6e tch buffer at on
c8c0: 63 65 20 70 65 72 20 74 68 72 65 61 64 2c 20 73 ce per thread, s
c8d0: 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 o.** N should be
c8e0: 20 73 65 74 20 74 6f 20 74 68 65 20 65 78 70 65 set to the expe
c8f0: 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d cted maximum num
c900: 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 20 ber of threads.
c910: 20 54 68 65 20 73 7a 0a 2a 2a 20 70 61 72 61 6d The sz.** param
c920: 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 36 eter should be 6
c930: 20 74 69 6d 65 73 20 74 68 65 20 73 69 7a 65 20 times the size
c940: 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 of the largest d
c950: 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a atabase page siz
c960: 65 2e 0a 2a 2a 20 53 63 72 61 74 63 68 20 62 75 e..** Scratch bu
c970: 66 66 65 72 73 20 61 72 65 20 75 73 65 64 20 61 ffers are used a
c980: 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 62 74 s part of the bt
c990: 72 65 65 20 62 61 6c 61 6e 63 65 20 6f 70 65 72 ree balance oper
c9a0: 61 74 69 6f 6e 2e 20 20 49 66 0a 2a 2a 20 54 68 ation. If.** Th
c9b0: 65 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65 72 e btree balancer
c9c0: 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 needs additiona
c9d0: 6c 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 l memory beyond
c9e0: 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 what is provided
c9f0: 20 62 79 0a 2a 2a 20 73 63 72 61 74 63 68 20 62 by.** scratch b
ca00: 75 66 66 65 72 73 20 6f 72 20 69 66 20 6e 6f 20 uffers or if no
ca10: 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 73 scratch buffer s
ca20: 70 61 63 65 20 69 73 20 73 70 65 63 69 66 69 65 pace is specifie
ca30: 64 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a d, then SQLite.*
ca40: 2a 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 * goes to [sqlit
ca50: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 74 6f 20 e3_malloc()] to
ca60: 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 obtain the memor
ca70: 79 20 69 74 20 6e 65 65 64 73 2e 3c 2f 64 64 3e y it needs.</dd>
ca80: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
ca90: 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 E_CONFIG_PAGECAC
caa0: 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 HE</dt>.** <dd>T
cab0: 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 his option speci
cac0: 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 fies a static me
cad0: 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 mory buffer that
cae0: 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 SQLite can use
caf0: 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 for.** the datab
cb00: 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 ase page cache w
cb10: 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 ith the default
cb20: 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 page cache imple
cb30: 6d 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 menation. .** T
cb40: 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f his configuratio
cb50: 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 n should not be
cb60: 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 used if an appli
cb70: 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 cation-define pa
cb80: 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c ge.** cache impl
cb90: 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f ementation is lo
cba0: 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 aded using the S
cbb0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
cbc0: 43 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 CHE option..** T
cbd0: 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 here are three a
cbe0: 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 rguments to this
cbf0: 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 option: A point
cc00: 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 er to 8-byte ali
cc10: 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 gned.** memory,
cc20: 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 the size of each
cc30: 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a page buffer (sz
cc40: 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 ), and the numbe
cc50: 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a r of pages (N)..
cc60: 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 ** The sz argume
cc70: 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 nt should be the
cc80: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 size of the lar
cc90: 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 gest database pa
cca0: 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f ge.** (a power o
ccb0: 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 f two between 51
ccc0: 32 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75 2 and 32768) plu
ccd0: 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61 s a little extra
cce0: 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 for each.** pag
ccf0: 65 20 68 65 61 64 65 72 2e 20 20 54 68 65 20 70 e header. The p
cd00: 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 20 age header size
cd10: 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 65 is 20 to 40 byte
cd20: 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a s depending on.*
cd30: 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 69 * the host archi
cd40: 74 65 63 74 75 72 65 2e 20 20 49 74 20 69 73 20 tecture. It is
cd50: 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 harmless, apart
cd60: 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 from the wasted
cd70: 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 memory,.** to ma
cd80: 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 ke sz a little t
cd90: 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20 66 oo large. The f
cda0: 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 irst.** argument
cdb0: 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f should point to
cdc0: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f an allocation o
cdd0: 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 f at least sz*N
cde0: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e bytes of memory.
cdf0: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 .** SQLite will
ce00: 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 use the memory p
ce10: 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66 rovided by the f
ce20: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
ce30: 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 satisfy its.**
ce40: 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 memory needs for
ce50: 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 the first N pag
ce60: 65 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20 es that it adds
ce70: 74 6f 20 63 61 63 68 65 2e 20 20 49 66 20 61 64 to cache. If ad
ce80: 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 ditional.** page
ce90: 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 cache memory is
cea0: 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 needed beyond w
ceb0: 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 hat is provided
cec0: 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 by this option,
ced0: 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 then.** SQLite g
cee0: 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f oes to [sqlite3_
cef0: 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 malloc()] for th
cf00: 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f e additional sto
cf10: 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 rage space..** T
cf20: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
cf30: 6e 20 6d 69 67 68 74 20 75 73 65 20 6f 6e 65 20 n might use one
cf40: 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 4e or more of the N
cf50: 20 62 75 66 66 65 72 73 20 74 6f 20 68 6f 6c 64 buffers to hold
cf60: 20 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 63 63 6f .** memory acco
cf70: 75 6e 74 69 6e 67 20 69 6e 66 6f 72 6d 61 74 69 unting informati
cf80: 6f 6e 2e 20 54 68 65 20 70 6f 69 6e 74 65 72 20 on. The pointer
cf90: 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 in the first arg
cfa0: 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 ument must.** be
cfb0: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 aligned to an 8
cfc0: 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f -byte boundary o
cfd0: 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 r subsequent beh
cfe0: 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a avior of SQLite.
cff0: 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 ** will be undef
d000: 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ined.</dd>.**.**
d010: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
d020: 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 IG_HEAP</dt>.**
d030: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 <dd>This option
d040: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 specifies a stat
d050: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 ic memory buffer
d060: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c that SQLite wil
d070: 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c l use.** for all
d080: 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 of its dynamic
d090: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
d0a0: 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 n needs beyond t
d0b0: 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a hose provided.**
d0c0: 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f for by [SQLITE_
d0d0: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 CONFIG_SCRATCH]
d0e0: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 and [SQLITE_CONF
d0f0: 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a IG_PAGECACHE]..*
d100: 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 * There are thre
d110: 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 e arguments: An
d120: 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 8-byte aligned p
d130: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 ointer to the me
d140: 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d mory,.** the num
d150: 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 ber of bytes in
d160: 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 the memory buffe
d170: 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d r, and the minim
d180: 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 um allocation si
d190: 7a 65 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 ze..** If the fi
d1a0: 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 rst pointer (the
d1b0: 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 memory pointer)
d1c0: 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 is NULL, then S
d1d0: 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a QLite reverts.**
d1e0: 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 to using its de
d1f0: 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c fault memory all
d200: 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 ocator (the syst
d210: 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c em malloc() impl
d220: 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 ementation),.**
d230: 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f undoing any prio
d240: 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 r invocation of
d250: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
d260: 41 4c 4c 4f 43 5d 2e 20 20 49 66 20 74 68 65 0a ALLOC]. If the.
d270: 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 ** memory pointe
d280: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e r is not NULL an
d290: 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 d either [SQLITE
d2a0: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d _ENABLE_MEMSYS3]
d2b0: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 or.** [SQLITE_E
d2c0: 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 NABLE_MEMSYS5] a
d2d0: 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e re defined, then
d2e0: 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 the alternative
d2f0: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 memory.** alloc
d300: 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 ator is engaged
d310: 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 to handle all of
d320: 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 SQLites memory
d330: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 allocation needs
d340: 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 ..** The first p
d350: 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f ointer (the memo
d360: 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 ry pointer) must
d370: 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 be aligned to a
d380: 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e n 8-byte.** boun
d390: 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 dary or subseque
d3a0: 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 nt behavior of S
d3b0: 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e QLite will be un
d3c0: 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a defined.</dd>.**
d3d0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
d3e0: 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e ONFIG_MUTEX</dt>
d3f0: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 .** <dd>This opt
d400: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
d410: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 le argument whic
d420: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 h is a pointer t
d430: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 o an.** instance
d440: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
d450: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 _mutex_methods]
d460: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 structure. The
d470: 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 argument specifi
d480: 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 es.** alternativ
d490: 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 e low-level mute
d4a0: 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 x routines to be
d4b0: 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a used in place.*
d4c0: 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 * the mutex rout
d4d0: 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 ines built into
d4e0: 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a SQLite.</dd>.**.
d4f0: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ** <dt>SQLITE_CO
d500: 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 NFIG_GETMUTEX</d
d510: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f t>.** <dd>This o
d520: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
d530: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 ngle argument wh
d540: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ich is a pointer
d550: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e to an.** instan
d560: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ce of the [sqlit
d570: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 e3_mutex_methods
d580: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 ] structure. Th
d590: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 e.** [sqlite3_mu
d5a0: 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 tex_methods].**
d5b0: 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c structure is fil
d5c0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 led with the cur
d5d0: 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d rently defined m
d5e0: 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 0a 2a utex routines..*
d5f0: 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 * This option ca
d600: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 n be used to ove
d610: 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c rload the defaul
d620: 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 t mutex allocati
d630: 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 on.** routines w
d640: 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 ith a wrapper us
d650: 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 ed to track mute
d660: 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 x usage for perf
d670: 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 ormance.** profi
d680: 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c ling or testing,
d690: 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 for example.</d
d6a0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
d6b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 ITE_CONFIG_LOOKA
d6c0: 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 SIDE</dt>.** <dd
d6d0: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b >This option tak
d6e0: 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 es two arguments
d6f0: 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 that determine
d700: 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d the default.** m
d710: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
d720: 20 6c 6f 6f 6b 61 73 69 64 65 20 6f 70 74 69 6d lookaside optim
d730: 69 7a 61 74 69 6f 6e 2e 20 20 54 68 65 20 66 69 ization. The fi
d740: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 rst argument is
d750: 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 the.** size of e
d760: 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 ach lookaside bu
d770: 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 ffer slot and th
d780: 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 e second is the
d790: 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f number of.** slo
d7a0: 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 ts allocated to
d7b0: 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f each database co
d7c0: 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 nnection. This
d7d0: 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a option sets the.
d7e0: 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 ** <i>default</i
d7f0: 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 > lookaside size
d800: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 . The [SQLITE_D
d810: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 BCONFIG_LOOKASID
d820: 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 E].** verb to [s
d830: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
d840: 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 ()] can be used
d850: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f to change the lo
d860: 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 okaside.** confi
d870: 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 guration on indi
d880: 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f vidual connectio
d890: 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c ns.</dd>.**.** <
d8a0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
d8b0: 5f 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 _PCACHE</dt>.**
d8c0: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 <dd>This option
d8d0: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
d8e0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
d8f0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a a pointer to.**
d900: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 an [sqlite3_pca
d910: 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a che_methods] obj
d920: 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 ect. This objec
d930: 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 t specifies the
d940: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 interface.** to
d950: 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 a custom page ca
d960: 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 che implementati
d970: 6f 6e 2e 20 20 53 51 4c 69 74 65 20 6d 61 6b 65 on. SQLite make
d980: 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a s a copy of the.
d990: 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 ** object and us
d9a0: 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 es it for page c
d9b0: 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ache memory allo
d9c0: 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a cations.</dd>.**
d9d0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
d9e0: 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 3c ONFIG_GETPCACHE<
d9f0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 /dt>.** <dd>This
da00: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
da10: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
da20: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 which is a point
da30: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c er to an.** [sql
da40: 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 ite3_pcache_meth
da50: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 ods] object. SQ
da60: 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 Lite copies of t
da70: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 he current.** pa
da80: 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 ge cache impleme
da90: 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 ntation into tha
daa0: 74 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a t object.</dd>.*
dab0: 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 *.** </dl>.*/.#d
dac0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
dad0: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 FIG_SINGLETHREAD
dae0: 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 1 /* nil */.#
daf0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
db00: 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 NFIG_MULTITHREAD
db10: 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 2 /* nil */.
db20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
db30: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 ONFIG_SERIALIZED
db40: 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 3 /* nil */
db50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
db60: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 CONFIG_MALLOC
db70: 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 4 /* sqlit
db80: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 e3_mem_methods*
db90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
dba0: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c E_CONFIG_GETMALL
dbb0: 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c OC 5 /* sql
dbc0: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
dbd0: 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
dbe0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 ITE_CONFIG_SCRAT
dbf0: 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 CH 6 /* v
dc00: 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e oid*, int sz, in
dc10: 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 t N */.#define S
dc20: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 QLITE_CONFIG_PAG
dc30: 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a ECACHE 7 /*
dc40: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 void*, int sz,
dc50: 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 int N */.#define
dc60: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 SQLITE_CONFIG_H
dc70: 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20 EAP 8
dc80: 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 /* void*, int nB
dc90: 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a yte, int min */.
dca0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
dcb0: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 ONFIG_MEMSTATUS
dcc0: 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 9 /* boolea
dcd0: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c n */.#define SQL
dce0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 ITE_CONFIG_MUTEX
dcf0: 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 10 /* s
dd00: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
dd10: 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 hods* */.#define
dd20: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 SQLITE_CONFIG_G
dd30: 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 ETMUTEX 11
dd40: 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 /* sqlite3_mutex
dd50: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 _methods* */./*
dd60: 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 previously SQLIT
dd70: 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c E_CONFIG_CHUNKAL
dd80: 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20 LOC 12 which is
dd90: 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a now unused. */ .
dda0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
ddb0: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 ONFIG_LOOKASIDE
ddc0: 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 13 /* int in
ddd0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
dde0: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 ITE_CONFIG_PCACH
ddf0: 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 73 E 14 /* s
de00: 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 qlite3_pcache_me
de10: 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e thods* */.#defin
de20: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
de30: 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 GETPCACHE 15
de40: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 /* sqlite3_pcac
de50: 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 0a he_methods* */..
de60: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
de70: 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 Configuration Op
de80: 74 69 6f 6e 73 20 7b 48 31 30 31 37 30 7d 20 3c tions {H10170} <
de90: 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52 S20000>.** EXPER
dea0: 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 IMENTAL.**.** Th
deb0: 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 ese constants ar
dec0: 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 e the available
ded0: 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 integer configur
dee0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 ation options th
def0: 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 at.** can be pas
df00: 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e sed as the secon
df10: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 d argument to th
df20: 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f e [sqlite3_db_co
df30: 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 nfig()] interfac
df40: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e e..**.** New con
df50: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
df60: 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 ns may be added
df70: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
df80: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a es of SQLite..**
df90: 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 Existing config
dfa0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 uration options
dfb0: 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 might be discont
dfc0: 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 inued. Applicat
dfd0: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 ions.** should c
dfe0: 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 heck the return
dff0: 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 code from [sqlit
e000: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 e3_db_config()]
e010: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 to make sure tha
e020: 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f t.** the call wo
e030: 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 rked. The [sqli
e040: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d te3_db_config()]
e050: 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 interface will
e060: 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d return a.** non-
e070: 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 zero [error code
e080: 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e ] if a discontin
e090: 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 ued or unsupport
e0a0: 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ed configuration
e0b0: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e option.** is in
e0c0: 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c voked..**.** <dl
e0d0: 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f >.** <dt>SQLITE_
e0e0: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 DBCONFIG_LOOKASI
e0f0: 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 DE</dt>.** <dd>T
e100: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
e110: 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 three additiona
e120: 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 l arguments that
e130: 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a determine the .
e140: 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 ** [lookaside me
e150: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 mory allocator]
e160: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f configuration fo
e170: 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 r the [database
e180: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 connection]..**
e190: 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
e1a0: 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61 nt (the third pa
e1b0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
e1c0: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d te3_db_config()]
e1d0: 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 is a.** pointer
e1e0: 20 74 6f 20 61 6e 20 6d 65 6d 6f 72 79 20 62 75 to an memory bu
e1f0: 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 ffer to use for
e200: 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 lookaside memory
e210: 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 ..** The first a
e220: 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 4e rgument may be N
e230: 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 ULL in which cas
e240: 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c e SQLite will al
e250: 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f locate the.** lo
e260: 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69 okaside buffer i
e270: 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c tself using [sql
e280: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 ite3_malloc()].
e290: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 The second argu
e2a0: 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 ment is the.** s
e2b0: 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b ize of each look
e2c0: 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f aside buffer slo
e2d0: 74 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 t and the third
e2e0: 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 argument is the
e2f0: 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f number of.** slo
e300: 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 ts. The size of
e310: 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 the buffer in t
e320: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
e330: 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 t must be greate
e340: 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 r than.** or equ
e350: 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 al to the produc
e360: 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 t of the second
e370: 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 and third argume
e380: 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 nts. The buffer
e390: 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 .** must be alig
e3a0: 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 ned to an 8-byte
e3b0: 20 62 6f 75 6e 64 61 72 79 2e 20 20 49 66 20 74 boundary. If t
e3c0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
e3d0: 6e 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 61 20 6d nt is not.** a m
e3e0: 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 ultiple of 8, it
e3f0: 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 20 72 is internally r
e400: 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 ounded down to t
e410: 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 0a he next smaller.
e420: 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 ** multiple of 8
e430: 2e 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 . See also: [SQ
e440: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b LITE_CONFIG_LOOK
e450: 41 53 49 44 45 5d 3c 2f 64 64 3e 0a 2a 2a 0a 2a ASIDE]</dd>.**.*
e460: 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 * </dl>.*/.#defi
e470: 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 ne SQLITE_DBCONF
e480: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 IG_LOOKASIDE
e490: 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 1001 /* void* i
e4a0: 6e 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a nt int */.../*.*
e4b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 * CAPI3REF: Enab
e4c0: 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 le Or Disable Ex
e4d0: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f tended Result Co
e4e0: 64 65 73 20 7b 48 31 32 32 30 30 7d 20 3c 53 31 des {H12200} <S1
e4f0: 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 0700>.**.** The
e500: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
e510: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 _result_codes()
e520: 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 routine enables
e530: 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a or disables the.
e540: 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 ** [extended res
e550: 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 ult codes] featu
e560: 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 54 68 re of SQLite. Th
e570: 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c e extended resul
e580: 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 t.** codes are d
e590: 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 isabled by defau
e5a0: 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 lt for historica
e5b0: 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 l compatibility
e5c0: 63 6f 6e 73 69 64 65 72 61 74 69 6f 6e 73 2e 0a considerations..
e5d0: 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
e5e0: 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 30 31 5d 20 ts:.** [H12201]
e5f0: 5b 48 31 32 32 30 32 5d 0a 2a 2f 0a 53 51 4c 49 [H12202].*/.SQLI
e600: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
e610: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 e3_extended_resu
e620: 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 lt_codes(sqlite3
e630: 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a *, int onoff);..
e640: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
e650: 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 Last Insert Rowi
e660: 64 20 7b 48 31 32 32 32 30 7d 20 3c 53 31 30 37 d {H12220} <S107
e670: 30 30 3e 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 00>.**.** Each e
e680: 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 ntry in an SQLit
e690: 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e e table has a un
e6a0: 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e ique 64-bit sign
e6b0: 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 ed.** integer ke
e6c0: 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f y called the [RO
e6d0: 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 WID | "rowid"].
e6e0: 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 The rowid is alw
e6f0: 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a ays available.**
e700: 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 as an undeclare
e710: 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 d column named R
e720: 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 OWID, OID, or _R
e730: 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 OWID_ as long as
e740: 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 those.** names
e750: 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 are not also use
e760: 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 d by explicitly
e770: 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 declared columns
e780: 2e 20 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c . If.** the tabl
e790: 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f e has a column o
e7a0: 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 f type [INTEGER
e7b0: 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 PRIMARY KEY] the
e7c0: 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a n that column.**
e7d0: 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 is another alia
e7e0: 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e s for the rowid.
e7f0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
e800: 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ine returns the
e810: 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 6d [rowid] of the m
e820: 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 ost recent.** su
e830: 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 ccessful [INSERT
e840: 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 ] into the datab
e850: 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 ase from the [da
e860: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
e870: 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 n].** in the fir
e880: 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 st argument. If
e890: 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b no successful [
e8a0: 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 INSERT]s.** have
e8b0: 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f ever occurred o
e8c0: 6e 20 74 68 61 74 20 64 61 74 61 62 61 73 65 20 n that database
e8d0: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f connection, zero
e8e0: 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
e8f0: 0a 2a 2a 20 49 66 20 61 6e 20 5b 49 4e 53 45 52 .** If an [INSER
e900: 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e T] occurs within
e910: 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e a trigger, then
e920: 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 the [rowid] of
e930: 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 the inserted.**
e940: 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 row is returned
e950: 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 by this routine
e960: 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 as long as the t
e970: 72 69 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e rigger is runnin
e980: 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 g..** But once t
e990: 68 65 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 he trigger termi
e9a0: 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 nates, the value
e9b0: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 returned by thi
e9c0: 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 s routine.** rev
e9d0: 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 erts to the last
e9e0: 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 value inserted
e9f0: 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 before the trigg
ea00: 65 72 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 er fired..**.**
ea10: 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 An [INSERT] that
ea20: 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 fails due to a
ea30: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 constraint viola
ea40: 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a tion is not a.**
ea50: 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 successful [INS
ea60: 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f ERT] and does no
ea70: 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c t change the val
ea80: 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 ue returned by t
ea90: 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 his.** routine.
eaa0: 20 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 Thus INSERT OR
eab0: 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 FAIL, INSERT OR
eac0: 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f IGNORE, INSERT O
ead0: 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 R ROLLBACK,.** a
eae0: 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f nd INSERT OR ABO
eaf0: 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 RT make no chang
eb00: 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e es to the return
eb10: 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a value of this.*
eb20: 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 * routine when t
eb30: 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 heir insertion f
eb40: 61 69 6c 73 2e 20 20 57 68 65 6e 20 49 4e 53 45 ails. When INSE
eb50: 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a RT OR REPLACE.**
eb60: 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f encounters a co
eb70: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 nstraint violati
eb80: 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 on, it does not
eb90: 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e fail. The.** IN
eba0: 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 SERT continues t
ebb0: 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 o completion aft
ebc0: 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 er deleting rows
ebd0: 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 that caused.**
ebe0: 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 the constraint p
ebf0: 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 roblem so INSERT
ec00: 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c OR REPLACE will
ec10: 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a always change.*
ec20: 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c * the return val
ec30: 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 ue of this inter
ec40: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 face..**.** For
ec50: 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 the purposes of
ec60: 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e this routine, an
ec70: 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e [INSERT] is con
ec80: 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 sidered to.** be
ec90: 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e successful even
eca0: 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 if it is subseq
ecb0: 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 uently rolled ba
ecc0: 63 6b 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 ck..**.** Requir
ecd0: 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 ements:.** [H122
ece0: 32 31 5d 20 5b 48 31 32 32 32 33 5d 0a 2a 2a 0a 21] [H12223].**.
ecf0: 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 ** If a separate
ed00: 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 thread performs
ed10: 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 a new [INSERT]
ed20: 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 on the same.** d
ed30: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
ed40: 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 on while the [sq
ed50: 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 lite3_last_inser
ed60: 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 t_rowid()].** fu
ed70: 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e nction is runnin
ed80: 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 g and thus chang
ed90: 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 es the last inse
eda0: 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 rt [rowid],.** t
edb0: 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 hen the value re
edc0: 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
edd0: 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 e3_last_insert_r
ede0: 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e owid()] is.** un
edf0: 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 predictable and
ee00: 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 might not equal
ee10: 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f either the old o
ee20: 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 r the new.** las
ee30: 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d t insert [rowid]
ee40: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
ee50: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 sqlite3_int64 sq
ee60: 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 lite3_last_inser
ee70: 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a t_rowid(sqlite3*
ee80: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
ee90: 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 EF: Count The Nu
eea0: 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 mber Of Rows Mod
eeb0: 69 66 69 65 64 20 7b 48 31 32 32 34 30 7d 20 3c ified {H12240} <
eec0: 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S10600>.**.** Th
eed0: 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 is function retu
eee0: 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
eef0: 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 f database rows
ef00: 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 that were change
ef10: 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 d.** or inserted
ef20: 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 or deleted by t
ef30: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 he most recently
ef40: 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 completed SQL s
ef50: 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 tatement.** on t
ef60: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
ef70: 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 nection] specifi
ef80: 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 ed by the first
ef90: 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 4f 6e parameter..** On
efa0: 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 ly changes that
efb0: 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 are directly spe
efc0: 63 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 cified by the [I
efd0: 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d NSERT], [UPDATE]
efe0: 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d ,.** or [DELETE]
eff0: 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 statement are c
f000: 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 ounted. Auxilia
f010: 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 ry changes cause
f020: 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 d by.** triggers
f030: 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 or [foreign key
f040: 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f actions] are no
f050: 74 20 63 6f 75 6e 74 65 64 2e 20 55 73 65 20 74 t counted. Use t
f060: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 he.** [sqlite3_t
f070: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 otal_changes()]
f080: 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 function to find
f090: 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 the total numbe
f0a0: 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 r of changes.**
f0b0: 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 including change
f0c0: 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67 s caused by trig
f0d0: 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e gers and foreign
f0e0: 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a key actions..**
f0f0: 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 .** Changes to a
f100: 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 73 view that are s
f110: 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b imulated by an [
f120: 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 INSTEAD OF trigg
f130: 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 er].** are not c
f140: 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 ounted. Only re
f150: 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73 al table changes
f160: 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a are counted..**
f170: 0a 2a 2a 20 41 20 22 72 6f 77 20 63 68 61 6e 67 .** A "row chang
f180: 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 e" is a change t
f190: 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f o a single row o
f1a0: 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 f a single table
f1b0: 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e .** caused by an
f1c0: 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c INSERT, DELETE,
f1d0: 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65 or UPDATE state
f1e0: 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 ment. Rows that
f1f0: 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 .** are changed
f200: 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20 as side effects
f210: 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e of [REPLACE] con
f220: 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 straint resoluti
f230: 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c on,.** rollback,
f240: 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e ABORT processin
f250: 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c g, [DROP TABLE],
f260: 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 or by any other
f270: 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 .** mechanisms d
f280: 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 o not count as d
f290: 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 irect row change
f2a0: 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 s..**.** A "trig
f2b0: 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 ger context" is
f2c0: 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 a scope of execu
f2d0: 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 tion that begins
f2e0: 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 and.** ends wit
f2f0: 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 h the script of
f300: 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 a [CREATE TRIGGE
f310: 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a R | trigger]. .*
f320: 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 * Most SQL state
f330: 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 ments are.** eva
f340: 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f luated outside o
f350: 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 f any trigger.
f360: 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 This is the "top
f370: 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 level".** trigg
f380: 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 er context. If
f390: 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20 a trigger fires
f3a0: 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 from the top lev
f3b0: 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 el, a.** new tri
f3c0: 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 gger context is
f3d0: 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 entered for the
f3e0: 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 duration of that
f3f0: 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e one.** trigger.
f400: 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72 Subtriggers cr
f410: 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 eate subcontexts
f420: 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 for their durat
f430: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 ion..**.** Calli
f440: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 ng [sqlite3_exec
f450: 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
f460: 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 step()] recursiv
f470: 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 ely does.** not
f480: 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 create a new tri
f490: 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a gger context..**
f4a0: 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f .** This functio
f4b0: 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 n returns the nu
f4c0: 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 mber of direct r
f4d0: 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 ow changes in th
f4e0: 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 e.** most recent
f4f0: 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c INSERT, UPDATE,
f500: 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 or DELETE state
f510: 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 ment within the
f520: 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 same.** trigger
f530: 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 context..**.** T
f540: 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 hus, when called
f550: 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 from the top le
f560: 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69 vel, this functi
f570: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a on returns the.*
f580: 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e * number of chan
f590: 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 ges in the most
f5a0: 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 recent INSERT, U
f5b0: 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 PDATE, or DELETE
f5c0: 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 .** that also oc
f5d0: 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74 6f curred at the to
f5e0: 70 20 6c 65 76 65 6c 2e 20 20 57 69 74 68 69 6e p level. Within
f5f0: 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 the body of a t
f600: 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 rigger,.** the s
f610: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 qlite3_changes()
f620: 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 interface can b
f630: 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 e called to find
f640: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a the number of.*
f650: 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 * changes in the
f660: 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 most recently c
f670: 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c ompleted INSERT,
f680: 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 UPDATE, or DELE
f690: 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 TE.** statement
f6a0: 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 within the body
f6b0: 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 of the same trig
f6c0: 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c ger..** However,
f6d0: 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 the number retu
f6e0: 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e rned does not in
f6f0: 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a clude changes.**
f700: 20 63 61 75 73 65 64 20 62 79 20 73 75 62 74 72 caused by subtr
f710: 69 67 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f iggers since tho
f720: 73 65 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 se have their ow
f730: 6e 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a n context..**.**
f740: 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 See also the [s
f750: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 qlite3_total_cha
f760: 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 nges()] interfac
f770: 65 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 63 6f e and the.** [co
f780: 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 unt_changes prag
f790: 6d 61 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 ma]..**.** Requi
f7a0: 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 rements:.** [H12
f7b0: 32 34 31 5d 20 5b 48 31 32 32 34 33 5d 0a 2a 2a 241] [H12243].**
f7c0: 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 .** If a separat
f7d0: 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 e thread makes c
f7e0: 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 hanges on the sa
f7f0: 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e me database conn
f800: 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 ection.** while
f810: 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 [sqlite3_changes
f820: 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 ()] is running t
f830: 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 hen the value re
f840: 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 turned.** is unp
f850: 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e redictable and n
f860: 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a ot meaningful..*
f870: 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
f880: 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 sqlite3_changes
f890: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
f8a0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 ** CAPI3REF: Tot
f8b0: 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 al Number Of Row
f8c0: 73 20 4d 6f 64 69 66 69 65 64 20 7b 48 31 32 32 s Modified {H122
f8d0: 36 30 7d 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 60} <S10600>.**.
f8e0: 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e ** This function
f8f0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
f900: 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 ber of row chang
f910: 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e es caused by [IN
f920: 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 SERT],.** [UPDAT
f930: 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 E] or [DELETE] s
f940: 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 tatements since
f950: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
f960: 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 nnection] was op
f970: 65 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 63 6f 75 ened..** The cou
f980: 6e 74 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 nt includes all
f990: 63 68 61 6e 67 65 73 20 66 72 6f 6d 20 61 6c 6c changes from all
f9a0: 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 [CREATE TRIGGER
f9b0: 20 7c 20 74 72 69 67 67 65 72 5d 20 0a 2a 2a 20 | trigger] .**
f9c0: 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61 contexts and cha
f9d0: 6e 67 65 73 20 6d 61 64 65 20 62 79 20 5b 66 6f nges made by [fo
f9e0: 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e reign key action
f9f0: 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 s]. However,.**
fa00: 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e the count does n
fa10: 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 ot include chang
fa20: 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 es used to imple
fa30: 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 ment [REPLACE] c
fa40: 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 onstraints,.** d
fa50: 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 o rollbacks or A
fa60: 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c BORT processing,
fa70: 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d or [DROP TABLE]
fa80: 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 processing. Th
fa90: 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 e.** count does
faa0: 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 not include rows
fab0: 20 6f 66 20 76 69 65 77 73 20 74 68 61 74 20 66 of views that f
fac0: 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 ire an [INSTEAD
fad0: 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 OF trigger],.**
fae0: 74 68 6f 75 67 68 20 69 66 20 74 68 65 20 49 4e though if the IN
faf0: 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 STEAD OF trigger
fb00: 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f makes changes o
fb10: 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 f its own, those
fb20: 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 changes .** are
fb30: 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 54 68 65 counted..** The
fb40: 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75 changes are cou
fb50: 6e 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 nted as soon as
fb60: 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 the statement th
fb70: 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 at makes them is
fb80: 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 .** completed (w
fb90: 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e hen the statemen
fba0: 74 20 68 61 6e 64 6c 65 20 69 73 20 70 61 73 73 t handle is pass
fbb0: 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 ed to [sqlite3_r
fbc0: 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 eset()] or.** [s
fbd0: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
fbe0: 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 )])..**.** See a
fbf0: 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 lso the [sqlite3
fc00: 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 _changes()] inte
fc10: 72 66 61 63 65 20 61 6e 64 20 74 68 65 0a 2a 2a rface and the.**
fc20: 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 [count_changes
fc30: 70 72 61 67 6d 61 5d 2e 0a 2a 2a 0a 2a 2a 20 52 pragma]..**.** R
fc40: 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
fc50: 5b 48 31 32 32 36 31 5d 20 5b 48 31 32 32 36 33 [H12261] [H12263
fc60: 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 ].**.** If a sep
fc70: 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b arate thread mak
fc80: 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 es changes on th
fc90: 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 e same database
fca0: 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 connection.** wh
fcb0: 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 ile [sqlite3_tot
fcc0: 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 al_changes()] is
fcd0: 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 running then th
fce0: 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 e value.** retur
fcf0: 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 ned is unpredict
fd00: 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 able and not mea
fd10: 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 ningful..*/.SQLI
fd20: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
fd30: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e3_total_changes
fd40: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
fd50: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 ** CAPI3REF: Int
fd60: 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 errupt A Long-Ru
fd70: 6e 6e 69 6e 67 20 51 75 65 72 79 20 7b 48 31 32 nning Query {H12
fd80: 32 37 30 7d 20 3c 53 33 30 35 30 30 3e 0a 2a 2a 270} <S30500>.**
fd90: 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f .** This functio
fda0: 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e n causes any pen
fdb0: 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 ding database op
fdc0: 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 eration to abort
fdd0: 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 and.** return a
fde0: 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f t its earliest o
fdf0: 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 pportunity. This
fe00: 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 routine is typi
fe10: 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 cally.** called
fe20: 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 in response to a
fe30: 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 user action suc
fe40: 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 h as pressing "C
fe50: 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 ancel".** or Ctr
fe60: 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 l-C where the us
fe70: 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 er wants a long
fe80: 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 query operation
fe90: 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 to halt.** immed
fea0: 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 iately..**.** It
feb0: 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c is safe to call
fec0: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 this routine fr
fed0: 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 om a thread diff
fee0: 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a erent from the.*
fef0: 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 * thread that is
ff00: 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 currently runni
ff10: 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ng the database
ff20: 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 operation. But
ff30: 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 it.** is not saf
ff40: 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 e to call this r
ff50: 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 outine with a [d
ff60: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
ff70: 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 on] that.** is c
ff80: 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 losed or might c
ff90: 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 lose before sqli
ffa0: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 te3_interrupt()
ffb0: 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 returns..**.** I
ffc0: 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 f an SQL operati
ffd0: 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c on is very nearl
ffe0: 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 y finished at th
fff0: 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 e time when.** s
10000 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
10010 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 () is called, th
10020 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 en it might not
10030 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e have an opportun
10040 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 ity.** to be int
10050 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 errupted and mig
10060 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 ht continue to c
10070 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a ompletion..**.**
10080 20 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f An SQL operatio
10090 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 n that is interr
100a0 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 upted will retur
100b0 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 n [SQLITE_INTERR
100c0 55 50 54 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 UPT]..** If the
100d0 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 interrupted SQL
100e0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 operation is an
100f0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 INSERT, UPDATE,
10100 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 or DELETE.** tha
10110 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 t is inside an e
10120 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 xplicit transact
10130 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e ion, then the en
10140 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e tire transaction
10150 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c .** will be roll
10160 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 ed back automati
10170 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 cally..**.** The
10180 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
10190 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e pt(D) call is in
101a0 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c effect until al
101b0 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e l currently runn
101c0 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 ing.** SQL state
101d0 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 ments on [databa
101e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
101f0 20 63 6f 6d 70 6c 65 74 65 2e 20 20 41 6e 79 20 complete. Any
10200 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e new SQL statemen
10210 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 ts.** that are s
10220 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 tarted after the
10230 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
10240 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 pt() call and be
10250 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e fore the .** run
10260 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 ning statements
10270 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 reaches zero are
10280 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 interrupted as
10290 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e if they had been
102a0 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f .** running prio
102b0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 r to the sqlite3
102c0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c _interrupt() cal
102d0 6c 2e 20 20 4e 65 77 20 53 51 4c 20 73 74 61 74 l. New SQL stat
102e0 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 ements.** that a
102f0 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 re started after
10300 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 the running sta
10310 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 tement count rea
10320 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a ches zero are.**
10330 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 not effected by
10340 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 the sqlite3_int
10350 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 41 20 63 errupt()..** A c
10360 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 all to sqlite3_i
10370 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 nterrupt(D) that
10380 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 occurs when the
10390 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e re are no runnin
103a0 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 g.** SQL stateme
103b0 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 nts is a no-op a
103c0 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 nd has no effect
103d0 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e on SQL statemen
103e0 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 ts.** that are s
103f0 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 tarted after the
10400 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
10410 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e pt() call return
10420 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 s..**.** Require
10430 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 37 ments:.** [H1227
10440 31 5d 20 5b 48 31 32 32 37 32 5d 0a 2a 2a 0a 2a 1] [H12272].**.*
10450 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 * If the databas
10460 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f e connection clo
10470 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 ses while [sqlit
10480 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a e3_interrupt()].
10490 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 ** is running th
104a0 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 en bad things wi
104b0 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e ll likely happen
104c0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
104d0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 void sqlite3_int
104e0 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 errupt(sqlite3*)
104f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
10500 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 F: Determine If
10510 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 An SQL Statement
10520 20 49 73 20 43 6f 6d 70 6c 65 74 65 20 7b 48 31 Is Complete {H1
10530 30 35 31 30 7d 20 3c 53 37 30 32 30 30 3e 0a 2a 0510} <S70200>.*
10540 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
10550 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 nes are useful d
10560 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 uring command-li
10570 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 ne input to dete
10580 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 rmine if the.**
10590 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 currently entere
105a0 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 d text seems to
105b0 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 form a complete
105c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 SQL statement or
105d0 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 .** if additiona
105e0 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 l input is neede
105f0 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 d before sending
10600 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a the text into.*
10610 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 * SQLite for par
10620 73 69 6e 67 2e 20 20 54 68 65 73 65 20 72 6f 75 sing. These rou
10630 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 tines return 1 i
10640 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 f the input stri
10650 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f ng.** appears to
10660 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 be a complete S
10670 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 41 QL statement. A
10680 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 statement is ju
10690 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f dged to be.** co
106a0 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 mplete if it end
106b0 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c s with a semicol
106c0 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 on token and is
106d0 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 not a prefix of
106e0 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 a.** well-formed
106f0 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 CREATE TRIGGER
10700 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 65 6d 69 statement. Semi
10710 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 colons that are
10720 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a embedded within.
10730 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 ** string litera
10740 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 ls or quoted ide
10750 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 ntifier names or
10760 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f comments are no
10770 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 t.** independent
10780 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 tokens (they ar
10790 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f e part of the to
107a0 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 ken in which the
107b0 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 y are.** embedde
107c0 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e d) and thus do n
107d0 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 ot count as a st
107e0 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 atement terminat
107f0 6f 72 2e 20 20 57 68 69 74 65 73 70 61 63 65 0a or. Whitespace.
10800 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 ** and comments
10810 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 that follow the
10820 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 final semicolon
10830 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a are ignored..**.
10840 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
10850 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 s return 0 if th
10860 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 e statement is i
10870 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 49 66 20 61 ncomplete. If a
10880 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 .** memory alloc
10890 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 ation fails, the
108a0 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 n SQLITE_NOMEM i
108b0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a s returned..**.*
108c0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
108d0 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 do not parse th
108e0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 e SQL statements
108f0 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f thus.** will no
10900 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 t detect syntact
10910 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 ically incorrect
10920 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 53 SQL..**.** If S
10930 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 QLite has not be
10940 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 en initialized u
10950 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e sing [sqlite3_in
10960 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f itialize()] prio
10970 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e r .** to invokin
10980 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 g sqlite3_comple
10990 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 te16() then sqli
109a0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
109b0 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 is invoked.** a
109c0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 utomatically by
109d0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 sqlite3_complete
109e0 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 16(). If that i
109f0 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 nitialization fa
10a00 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ils,.** then the
10a10 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 return value fr
10a20 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c om sqlite3_compl
10a30 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 ete16() will be
10a40 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 non-zero.** rega
10a50 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 rdless of whethe
10a60 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 r or not the inp
10a70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 ut SQL is comple
10a80 74 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 te..**.** Requir
10a90 65 6d 65 6e 74 73 3a 20 5b 48 31 30 35 31 31 5d ements: [H10511]
10aa0 20 5b 48 31 30 35 31 32 5d 0a 2a 2a 0a 2a 2a 20 [H10512].**.**
10ab0 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 The input to [sq
10ac0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 lite3_complete()
10ad0 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f ] must be a zero
10ae0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 -terminated.** U
10af0 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a TF-8 string..**.
10b00 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 ** The input to
10b10 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 [sqlite3_complet
10b20 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 e16()] must be a
10b30 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
10b40 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e .** UTF-16 strin
10b50 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 g in native byte
10b60 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 order..*/.SQLIT
10b70 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
10b80 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 3_complete(const
10b90 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 53 51 4c char *sql);.SQL
10ba0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
10bb0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 te3_complete16(c
10bc0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b onst void *sql);
10bd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
10be0 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c : Register A Cal
10bf0 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 lback To Handle
10c00 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f SQLITE_BUSY Erro
10c10 72 73 20 7b 48 31 32 33 31 30 7d 20 3c 53 34 30 rs {H12310} <S40
10c20 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 400>.**.** This
10c30 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 routine sets a c
10c40 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
10c50 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 that might be i
10c60 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a nvoked whenever.
10c70 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 ** an attempt is
10c80 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 made to open a
10c90 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 database table t
10ca0 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 hat another thre
10cb0 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 ad.** or process
10cc0 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a has locked..**.
10cd0 2a 2a 20 49 66 20 74 68 65 20 62 75 73 79 20 63 ** If the busy c
10ce0 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c allback is NULL,
10cf0 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 then [SQLITE_BU
10d00 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 SY] or [SQLITE_I
10d10 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a OERR_BLOCKED].**
10d20 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d is returned imm
10d30 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e ediately upon en
10d40 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c countering the l
10d50 6f 63 6b 2e 20 49 66 20 74 68 65 20 62 75 73 79 ock. If the busy
10d60 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 callback.** is
10d70 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 not NULL, then t
10d80 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c he callback will
10d90 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 be invoked with
10da0 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a two arguments..
10db0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
10dc0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
10dd0 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 handler is a cop
10de0 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 y of the void* p
10df0 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 ointer which.**
10e00 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 is the third arg
10e10 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 ument to sqlite3
10e20 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e _busy_handler().
10e30 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 The second arg
10e40 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 ument to.** the
10e50 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b handler callback
10e60 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f is the number o
10e70 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 f times that the
10e80 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 busy handler ha
10e90 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 s.** been invoke
10ea0 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 d for this locki
10eb0 6e 67 20 65 76 65 6e 74 2e 20 20 49 66 20 74 68 ng event. If th
10ec0 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 e.** busy callba
10ed0 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 ck returns 0, th
10ee0 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c en no additional
10ef0 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 attempts are ma
10f00 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 de to.** access
10f10 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 the database and
10f20 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f [SQLITE_BUSY] o
10f30 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f r [SQLITE_IOERR_
10f40 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 BLOCKED] is retu
10f50 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 rned..** If the
10f60 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
10f70 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 non-zero, then
10f80 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a another attempt.
10f90 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 ** is made to op
10fa0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
10fb0 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 for reading and
10fc0 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 the cycle repeat
10fd0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 s..**.** The pre
10fe0 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 sence of a busy
10ff0 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 handler does not
11000 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 guarantee that
11010 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b it will be invok
11020 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 ed.** when there
11030 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 is lock content
11040 69 6f 6e 2e 20 49 66 20 53 51 4c 69 74 65 20 64 ion. If SQLite d
11050 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 etermines that i
11060 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 nvoking the busy
11070 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c .** handler coul
11080 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 d result in a de
11090 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 adlock, it will
110a0 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 go ahead and ret
110b0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 urn [SQLITE_BUSY
110c0 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f ].** or [SQLITE_
110d0 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 IOERR_BLOCKED] i
110e0 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 nstead of invoki
110f0 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ng the busy hand
11100 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 ler..** Consider
11110 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 a scenario wher
11120 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 e one process is
11130 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 holding a read
11140 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 lock that.** it
11150 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f is trying to pro
11160 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 mote to a reserv
11170 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 ed lock and.** a
11180 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 second process
11190 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 is holding a res
111a0 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 erved lock that
111b0 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 it is trying.**
111c0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e to promote to an
111d0 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e exclusive lock.
111e0 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 The first proc
111f0 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 ess cannot proce
11200 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 ed.** because it
11210 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 is blocked by t
11220 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 he second and th
11230 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 e second process
11240 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 cannot.** proce
11250 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 ed because it is
11260 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 blocked by the
11270 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 first. If both
11280 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 processes.** inv
11290 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e oke the busy han
112a0 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 dlers, neither w
112b0 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f ill make any pro
112c0 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 gress. Therefor
112d0 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 e,.** SQLite ret
112e0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 urns [SQLITE_BUS
112f0 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 Y] for the first
11300 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 process, hoping
11310 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 that this.** wi
11320 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 ll induce the fi
11330 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 rst process to r
11340 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 elease its read
11350 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a lock and allow.*
11360 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f * the second pro
11370 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e cess to proceed.
11380 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 .**.** The defau
11390 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b lt busy callback
113a0 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 is NULL..**.**
113b0 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 The [SQLITE_BUSY
113c0 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 ] error is conve
113d0 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f rted to [SQLITE_
113e0 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a IOERR_BLOCKED].*
113f0 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 * when SQLite is
11400 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f in the middle o
11410 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 f a large transa
11420 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 ction where all
11430 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 the.** changes w
11440 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f ill not fit into
11450 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 the in-memory c
11460 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 ache. SQLite wi
11470 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f ll.** already ho
11480 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f ld a RESERVED lo
11490 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 ck on the databa
114a0 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 se file, but it
114b0 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d needs.** to prom
114c0 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f ote this lock to
114d0 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 EXCLUSIVE so th
114e0 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 at it can spill
114f0 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 cache.** pages i
11500 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 nto the database
11510 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 file without ha
11520 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 rm to concurrent
11530 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 49 66 .** readers. If
11540 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f it is unable to
11550 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 promote the loc
11560 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d k, then the in-m
11570 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 emory.** cache w
11580 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 ill be left in a
11590 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 n inconsistent s
115a0 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 tate and so the
115b0 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 error.** code is
115c0 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 promoted from t
115d0 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 he relatively be
115e0 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 nign [SQLITE_BUS
115f0 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 Y] to.** the mor
11600 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 e severe [SQLITE
11610 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e _IOERR_BLOCKED].
11620 20 20 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 This error cod
11630 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 e promotion.** f
11640 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 orces an automat
11650 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 ic rollback of t
11660 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 he changes. See
11670 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d the.** <a href=
11680 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 "/cvstrac/wiki?p
11690 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f =CorruptionFollo
116a0 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a wingBusyError">.
116b0 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c ** CorruptionFol
116c0 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c lowingBusyError<
116d0 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f /a> wiki page fo
116e0 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f r a discussion o
116f0 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 f why.** this is
11700 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a important..**.*
11710 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 * There can only
11720 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 be a single bus
11730 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 y handler define
11740 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 d for each.** [d
11750 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
11760 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 on]. Setting a
11770 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 new busy handler
11780 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 clears any.** p
11790 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 reviously set ha
117a0 6e 64 6c 65 72 2e 20 20 4e 6f 74 65 20 74 68 61 ndler. Note tha
117b0 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 t calling [sqlit
117c0 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 e3_busy_timeout(
117d0 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 )].** will also
117e0 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 set or clear the
117f0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a busy handler..*
11800 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 *.** The busy ca
11810 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f llback should no
11820 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f t take any actio
11830 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 ns which modify
11840 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 the.** database
11850 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 connection that
11860 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 invoked the busy
11870 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 handler. Any s
11880 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 uch actions.** r
11890 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e esult in undefin
118a0 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 ed behavior..**
118b0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
118c0 3a 0a 2a 2a 20 5b 48 31 32 33 31 31 5d 20 5b 48 :.** [H12311] [H
118d0 31 32 33 31 32 5d 20 5b 48 31 32 33 31 34 5d 20 12312] [H12314]
118e0 5b 48 31 32 33 31 36 5d 20 5b 48 31 32 33 31 38 [H12316] [H12318
118f0 5d 0a 2a 2a 0a 2a 2a 20 41 20 62 75 73 79 20 68 ].**.** A busy h
11900 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 andler must not
11910 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 close the databa
11920 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se connection.**
11930 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 or [prepared st
11940 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e atement] that in
11950 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 voked the busy h
11960 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 andler..*/.SQLIT
11970 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
11980 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 3_busy_handler(s
11990 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 qlite3*, int(*)(
119a0 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 void*,int), void
119b0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
119c0 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 REF: Set A Busy
119d0 54 69 6d 65 6f 75 74 20 7b 48 31 32 33 34 30 7d Timeout {H12340}
119e0 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 <S40410>.**.**
119f0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 This routine set
11a00 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 s a [sqlite3_bus
11a10 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 y_handler | busy
11a20 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 handler] that s
11a30 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 leeps.** for a s
11a40 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 pecified amount
11a50 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 of time when a t
11a60 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 able is locked.
11a70 20 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 The handler.**
11a80 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 will sleep multi
11a90 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 ple times until
11aa0 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 at least "ms" mi
11ab0 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c lliseconds of sl
11ac0 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 eeping.** have a
11ad0 63 63 75 6d 75 6c 61 74 65 64 2e 20 7b 48 31 32 ccumulated. {H12
11ae0 33 34 33 7d 20 41 66 74 65 72 20 22 6d 73 22 20 343} After "ms"
11af0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 milliseconds of
11b00 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 sleeping,.** the
11b10 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 handler returns
11b20 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 0 which causes
11b30 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
11b40 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 to return.** [S
11b50 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b QLITE_BUSY] or [
11b60 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f SQLITE_IOERR_BLO
11b70 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c CKED]..**.** Cal
11b80 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e ling this routin
11b90 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 e with an argume
11ba0 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 nt less than or
11bb0 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a equal to zero.**
11bc0 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 turns off all b
11bd0 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a usy handlers..**
11be0 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e .** There can on
11bf0 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 ly be a single b
11c00 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 usy handler for
11c10 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 a particular.**
11c20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
11c30 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 tion] any any gi
11c40 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 ven moment. If
11c50 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e another busy han
11c60 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 dler.** was defi
11c70 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c ned (using [sql
11c80 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 ite3_busy_handle
11c90 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 r()]) prior to c
11ca0 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 alling.** this r
11cb0 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 outine, that oth
11cc0 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 er busy handler
11cd0 69 73 20 63 6c 65 61 72 65 64 2e 0a 2a 2a 0a 2a is cleared..**.*
11ce0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
11cf0 2a 2a 20 5b 48 31 32 33 34 31 5d 20 5b 48 31 32 ** [H12341] [H12
11d00 33 34 33 5d 20 5b 48 31 32 33 34 34 5d 0a 2a 2f 343] [H12344].*/
11d10 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
11d20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d sqlite3_busy_tim
11d30 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 eout(sqlite3*, i
11d40 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 nt ms);../*.** C
11d50 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 API3REF: Conveni
11d60 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f ence Routines Fo
11d70 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 r Running Querie
11d80 73 20 7b 48 31 32 33 37 30 7d 20 3c 53 31 30 30 s {H12370} <S100
11d90 30 30 3e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 00>.**.** Defini
11da0 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c tion: A <b>resul
11db0 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d t table</b> is m
11dc0 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 emory data struc
11dd0 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 ture created by
11de0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
11df0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 get_table()] int
11e00 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c erface. A resul
11e10 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 t table records
11e20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 the.** complete
11e30 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 query results fr
11e40 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 om one or more q
11e50 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 ueries..**.** Th
11e60 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 e table conceptu
11e70 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 ally has a numbe
11e80 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f r of rows and co
11e90 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 lumns. But.** t
11ea0 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 hese numbers are
11eb0 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 not part of the
11ec0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 result table it
11ed0 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 self. These.**
11ee0 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 numbers are obta
11ef0 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e ined separately.
11f00 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e Let N be the n
11f10 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a umber of rows.**
11f20 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 and M be the nu
11f30 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e mber of columns.
11f40 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 .**.** A result
11f50 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 table is an arra
11f60 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f y of pointers to
11f70 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
11f80 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a UTF-8 strings..
11f90 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b ** There are (N+
11fa0 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 1)*M elements in
11fb0 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 the array. The
11fc0 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 first M pointer
11fd0 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 s point.** to ze
11fe0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 ro-terminated st
11ff0 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 rings that cont
12000 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 ain the names of
12010 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a the columns..**
12020 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 The remaining e
12030 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 ntries all point
12040 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 to query result
12050 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 s. NULL values
12060 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c result.** in NUL
12070 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c L pointers. All
12080 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 other values ar
12090 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 e in their UTF-8
120a0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
120b0 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 .** string repre
120c0 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 sentation as ret
120d0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 urned by [sqlite
120e0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 3_column_text()]
120f0 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 ..**.** A result
12100 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e table might con
12110 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d sist of one or m
12120 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ore memory alloc
12130 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 ations..** It is
12140 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 not safe to pas
12150 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 s a result table
12160 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 directly to [sq
12170 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a lite3_free()]..*
12180 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 * A result table
12190 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c should be deall
121a0 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 ocated using [sq
121b0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 lite3_free_table
121c0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e ()]..**.** As an
121d0 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 example of the
121e0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 result table for
121f0 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 mat, suppose a q
12200 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 uery result.** i
12210 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a s as follows:.**
12220 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
12230 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 <pre>.**
12240 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 Name | Ag
12250 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d e.** ----
12260 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
12270 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c ---.** Al
12280 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a ice | 43.*
12290 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 * Bob
122a0 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 | 28.**
122b0 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 Cindy
122c0 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f | 21.** </pre></
122d0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
122e0 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 * There are two
122f0 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e column (M==2) an
12300 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d d three rows (N=
12310 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a =3). Thus the.*
12320 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 * result table h
12330 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 as 8 entries. S
12340 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c uppose the resul
12350 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 t table is store
12360 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 d.** in an array
12370 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e names azResult.
12380 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 Then azResult
12390 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 holds this conte
123a0 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b nt:.**.** <block
123b0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
123c0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
123d0 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 91;0] = "Name";.
123e0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
123f0 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 lt[1] = "Age
12400 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
12410 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 esult[2] = "
12420 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 Alice";.**
12430 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 azResult[3
12440 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 ] = "43";.**
12450 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
12460 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 ;4] = "Bob";.**
12470 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
12480 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a #91;5] = "28";.*
12490 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
124a0 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 t[6] = "Cind
124b0 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a y";.** az
124c0 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 Result[7] =
124d0 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c "21";.** </pre><
124e0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
124f0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 ** The sqlite3_g
12500 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 et_table() funct
12510 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e ion evaluates on
12520 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d e or more.** sem
12530 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 icolon-separated
12540 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
12550 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d in the zero-term
12560 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 inated UTF-8.**
12570 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e string of its 2n
12580 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 74 d parameter. It
12590 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c returns a resul
125a0 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a t table to the.*
125b0 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 * pointer given
125c0 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d in its 3rd param
125d0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 eter..**.** Afte
125e0 72 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 r the calling fu
125f0 6e 63 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 nction has finis
12600 68 65 64 20 75 73 69 6e 67 20 74 68 65 20 72 65 hed using the re
12610 73 75 6c 74 2c 20 69 74 20 73 68 6f 75 6c 64 0a sult, it should.
12620 2a 2a 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e ** pass the poin
12630 74 65 72 20 74 6f 20 74 68 65 20 72 65 73 75 6c ter to the resul
12640 74 20 74 61 62 6c 65 20 74 6f 20 73 71 6c 69 74 t table to sqlit
12650 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 e3_free_table()
12660 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 in order to.** r
12670 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 elease the memor
12680 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f y that was mallo
12690 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 ced. Because of
126a0 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 the way the.**
126b0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
126c0 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 )] happens withi
126d0 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 n sqlite3_get_ta
126e0 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 ble(), the calli
126f0 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d ng.** function m
12700 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 ust not try to c
12710 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 all [sqlite3_fre
12720 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 e()] directly.
12730 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 Only.** [sqlite3
12740 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 _free_table()] i
12750 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 s able to releas
12760 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f e the memory pro
12770 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 perly and safely
12780 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
12790 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 te3_get_table()
127a0 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 interface is imp
127b0 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 lemented as a wr
127c0 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 apper around.**
127d0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
127e0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 . The sqlite3_g
127f0 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 et_table() routi
12800 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 ne does not have
12810 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e access.** to an
12820 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 y internal data
12830 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 structures of SQ
12840 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f Lite. It uses o
12850 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a nly the public.*
12860 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 * interface defi
12870 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 ned here. As a
12880 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 consequence, err
12890 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 ors that occur i
128a0 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 n the.** wrapper
128b0 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f layer outside o
128c0 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b f the internal [
128d0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 sqlite3_exec()]
128e0 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 call are not.**
128f0 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 reflected in sub
12900 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f sequent calls to
12910 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 [sqlite3_errcod
12920 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 e()] or [sqlite3
12930 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a _errmsg()]..**.*
12940 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
12950 2a 2a 20 5b 48 31 32 33 37 31 5d 20 5b 48 31 32 ** [H12371] [H12
12960 33 37 33 5d 20 5b 48 31 32 33 37 34 5d 20 5b 48 373] [H12374] [H
12970 31 32 33 37 36 5d 20 5b 48 31 32 33 37 39 5d 20 12376] [H12379]
12980 5b 48 31 32 33 38 32 5d 0a 2a 2f 0a 53 51 4c 49 [H12382].*/.SQLI
12990 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
129a0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 e3_get_table(.
129b0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
129c0 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e /* An open
129d0 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 database */. c
129e0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c onst char *zSql,
129f0 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 /* SQL to b
12a00 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 e evaluated */.
12a10 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 char ***pazResu
12a20 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 lt, /* Result
12a30 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a s of the query *
12a40 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 /. int *pnRow,
12a50 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d /* Num
12a60 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f ber of result ro
12a70 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 ws written here
12a80 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 */. int *pnColu
12a90 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 mn, /* Nu
12aa0 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 mber of result c
12ab0 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 olumns written h
12ac0 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a ere */. char **
12ad0 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f pzErrmsg /
12ae0 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 * Error msg writ
12af0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 ten here */.);.S
12b00 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
12b10 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c qlite3_free_tabl
12b20 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 e(char **result)
12b30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
12b40 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 F: Formatted Str
12b50 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e ing Printing Fun
12b60 63 74 69 6f 6e 73 20 7b 48 31 37 34 30 30 7d 20 ctions {H17400}
12b70 3c 53 37 30 30 30 30 3e 3c 53 32 30 30 30 30 3e <S70000><S20000>
12b80 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
12b90 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 tines are work-a
12ba0 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 likes of the "pr
12bb0 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f intf()" family o
12bc0 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 f functions.** f
12bd0 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 rom the standard
12be0 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a C library..**.*
12bf0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 * The sqlite3_mp
12c00 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 rintf() and sqli
12c10 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 te3_vmprintf() r
12c20 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 outines write th
12c30 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 eir.** results i
12c40 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 nto memory obtai
12c50 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ned from [sqlite
12c60 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 3_malloc()]..**
12c70 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 The strings retu
12c80 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 rned by these tw
12c90 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c o routines shoul
12ca0 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 d be.** released
12cb0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 by [sqlite3_fre
12cc0 65 28 29 5d 2e 20 20 42 6f 74 68 20 72 6f 75 74 e()]. Both rout
12cd0 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a ines return a.**
12ce0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 NULL pointer if
12cf0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
12d00 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f ()] is unable to
12d10 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 allocate enough
12d20 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f .** memory to ho
12d30 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 ld the resulting
12d40 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 string..**.** I
12d50 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e n sqlite3_snprin
12d60 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 tf() routine is
12d70 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 similar to "snpr
12d80 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 intf()" from.**
12d90 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c the standard C l
12da0 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 ibrary. The res
12db0 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 ult is written i
12dc0 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 nto the.** buffe
12dd0 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 r supplied as th
12de0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
12df0 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 er whose size is
12e00 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 given by.** the
12e10 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
12e20 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 . Note that the
12e30 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 order of the.**
12e40 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 first two parame
12e50 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 ters is reversed
12e60 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 from snprintf()
12e70 2e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a . This is an.**
12e80 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 historical acci
12e90 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 dent that cannot
12ea0 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 be fixed withou
12eb0 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 t breaking.** ba
12ec0 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 ckwards compatib
12ed0 69 6c 69 74 79 2e 20 20 4e 6f 74 65 20 61 6c 73 ility. Note als
12ee0 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 o that sqlite3_s
12ef0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 nprintf().** ret
12f00 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
12f10 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 o its buffer ins
12f20 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 tead of the numb
12f30 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 er of.** charact
12f40 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 ers actually wri
12f50 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 tten into the bu
12f60 66 66 65 72 2e 20 20 57 65 20 61 64 6d 69 74 20 ffer. We admit
12f70 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 that.** the numb
12f80 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 er of characters
12f90 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 written would b
12fa0 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 e a more useful
12fb0 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 return.** value
12fc0 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 but we cannot ch
12fd0 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 ange the impleme
12fe0 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 ntation of sqlit
12ff0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a e3_snprintf().**
13000 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 now without bre
13010 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c aking compatibil
13020 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f ity..**.** As lo
13030 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 ng as the buffer
13040 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 size is greater
13050 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 than zero, sqli
13060 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a te3_snprintf().*
13070 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 * guarantees tha
13080 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 t the buffer is
13090 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d always zero-term
130a0 69 6e 61 74 65 64 2e 20 20 54 68 65 20 66 69 72 inated. The fir
130b0 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 st.** parameter
130c0 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c "n" is the total
130d0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 size of the buf
130e0 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 fer, including s
130f0 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 pace for.** the
13100 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e zero terminator.
13110 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 So the longest
13120 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e string that can
13130 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a be completely.*
13140 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 * written will b
13150 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 e n-1 characters
13160 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f ..**.** These ro
13170 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 utines all imple
13180 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 ment some additi
13190 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a onal formatting.
131a0 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 ** options that
131b0 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 are useful for c
131c0 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 onstructing SQL
131d0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 statements..** A
131e0 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 ll of the usual
131f0 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 printf() formatt
13200 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c ing options appl
13210 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c y. In addition,
13220 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 there.** is are
13230 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 "%q", "%Q", and
13240 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a "%z" options..*
13250 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70 74 69 *.** The %q opti
13260 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 on works like %s
13270 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 in that it subs
13280 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 titutes a null-t
13290 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 erminated.** str
132a0 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 ing from the arg
132b0 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 ument list. But
132c0 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 %q also doubles
132d0 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 every '\'' char
132e0 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 acter..** %q is
132f0 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 designed for use
13300 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 inside a string
13310 20 6c 69 74 65 72 61 6c 2e 20 20 42 79 20 64 6f literal. By do
13320 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 ubling each '\''
13330 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 .** character it
13340 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 escapes that ch
13350 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f aracter and allo
13360 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 ws it to be inse
13370 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 rted into.** the
13380 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 string..**.** F
13390 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 or example, assu
133a0 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 me the string va
133b0 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e riable zText con
133c0 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f tains text as fo
133d0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c llows:.**.** <bl
133e0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
133f0 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d * char *zText =
13400 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64 "It's a happy d
13410 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c ay!";.** </pre><
13420 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
13430 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 ** One can use t
13440 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 his text in an S
13450 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 QL statement as
13460 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c follows:.**.** <
13470 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
13480 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 .** char *zSQL
13490 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 = sqlite3_mprint
134a0 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 f("INSERT INTO t
134b0 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 able VALUES('%q'
134c0 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 )", zText);.**
134d0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c sqlite3_exec(db,
134e0 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b zSQL, 0, 0, 0);
134f0 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 .** sqlite3_fre
13500 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 e(zSQL);.** </pr
13510 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a e></blockquote>.
13520 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 **.** Because th
13530 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 e %q format stri
13540 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 ng is used, the
13550 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69 '\'' character i
13560 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 n zText.** is es
13570 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 caped and the SQ
13580 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 L generated is a
13590 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a s follows:.**.**
135a0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
135b0 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e e>.** INSERT IN
135c0 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 TO table1 VALUES
135d0 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20 ('It''s a happy
135e0 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e day!').** </pre>
135f0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a </blockquote>.**
13600 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 .** This is corr
13610 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 ect. Had we use
13620 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 d %s instead of
13630 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 %q, the generate
13640 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 d SQL.** would h
13650 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 ave looked like
13660 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f this:.**.** <blo
13670 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a ckquote><pre>.**
13680 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 INSERT INTO ta
13690 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 ble1 VALUES('It'
136a0 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 s a happy day!')
136b0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f ;.** </pre></blo
136c0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 ckquote>.**.** T
136d0 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 his second examp
136e0 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e le is an SQL syn
136f0 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 tax error. As a
13700 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f general rule yo
13710 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 u should.** alwa
13720 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 ys use %q instea
13730 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 d of %s when ins
13740 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f erting text into
13750 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 a string litera
13760 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 51 20 l..**.** The %Q
13770 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b option works lik
13780 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 e %q except it a
13790 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 lso adds single
137a0 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a quotes around.**
137b0 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 the outside of
137c0 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 the total string
137d0 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c . Additionally,
137e0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 if the paramete
137f0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 r in the.** argu
13800 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e ment list is a N
13810 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 ULL pointer, %Q
13820 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 substitutes the
13830 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 text "NULL" (wit
13840 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 hout.** single q
13850 75 6f 74 65 73 29 20 69 6e 20 70 6c 61 63 65 20 uotes) in place
13860 6f 66 20 74 68 65 20 25 51 20 6f 70 74 69 6f 6e of the %Q option
13870 2e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 . So, for examp
13880 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 le, one could sa
13890 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 y:.**.** <blockq
138a0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 uote><pre>.** c
138b0 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 har *zSQL = sqli
138c0 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 te3_mprintf("INS
138d0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 ERT INTO table V
138e0 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 ALUES(%Q)", zTex
138f0 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f t);.** sqlite3_
13900 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 exec(db, zSQL, 0
13910 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c , 0, 0);.** sql
13920 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b ite3_free(zSQL);
13930 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
13940 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 kquote>.**.** Th
13950 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c e code above wil
13960 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 l render a corre
13970 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ct SQL statement
13980 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 in the zSQL.**
13990 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 variable even if
139a0 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 the zText varia
139b0 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f ble is a NULL po
139c0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 inter..**.** The
139d0 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 "%z" formatting
139e0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 65 78 option works ex
139f0 61 63 74 6c 79 20 6c 69 6b 65 20 22 25 73 22 20 actly like "%s"
13a00 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 with the.** addi
13a10 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 tion that after
13a20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 the string has b
13a30 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 een read and cop
13a40 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 ied into.** the
13a50 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 result, [sqlite3
13a60 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c _free()] is call
13a70 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 ed on the input
13a80 73 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a 2a 2a string. {END}.**
13a90 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 .** Requirements
13aa0 3a 0a 2a 2a 20 5b 48 31 37 34 30 33 5d 20 5b 48 :.** [H17403] [H
13ab0 31 37 34 30 36 5d 20 5b 48 31 37 34 30 37 5d 0a 17406] [H17407].
13ac0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 */.SQLITE_API ch
13ad0 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 ar *sqlite3_mpri
13ae0 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c ntf(const char*,
13af0 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ...);.SQLITE_API
13b00 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 char *sqlite3_v
13b10 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 mprintf(const ch
13b20 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 53 ar*, va_list);.S
13b30 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a QLITE_API char *
13b40 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
13b50 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 (int,char*,const
13b60 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f char*, ...);../
13b70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d *.** CAPI3REF: M
13b80 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e emory Allocation
13b90 20 53 75 62 73 79 73 74 65 6d 20 7b 48 31 37 33 Subsystem {H173
13ba0 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 00} <S20000>.**.
13bb0 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f ** The SQLite co
13bc0 72 65 20 20 75 73 65 73 20 74 68 65 73 65 20 74 re uses these t
13bd0 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f hree routines fo
13be0 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e r all of its own
13bf0 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d .** internal mem
13c00 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e ory allocation n
13c10 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 eeds. "Core" in
13c20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e the previous sen
13c30 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f tence.** does no
13c40 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 t include operat
13c50 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 ing-system speci
13c60 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e fic VFS implemen
13c70 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 tation. The.**
13c80 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 Windows VFS uses
13c90 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 native malloc()
13ca0 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 and free() for
13cb0 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e some operations.
13cc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
13cd0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 e3_malloc() rout
13ce0 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f ine returns a po
13cf0 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b inter to a block
13d00 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 .** of memory at
13d10 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 least N bytes i
13d20 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 n length, where
13d30 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 N is the paramet
13d40 65 72 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 er..** If sqlite
13d50 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 3_malloc() is un
13d60 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 able to obtain s
13d70 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a ufficient free.*
13d80 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 * memory, it ret
13d90 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e urns a NULL poin
13da0 74 65 72 2e 20 20 49 66 20 74 68 65 20 70 61 72 ter. If the par
13db0 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 ameter N to.** s
13dc0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
13dd0 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 is zero or negat
13de0 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 ive then sqlite3
13df0 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e _malloc() return
13e00 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e s.** a NULL poin
13e10 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 ter..**.** Calli
13e20 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 ng sqlite3_free(
13e30 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 ) with a pointer
13e40 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 previously retu
13e50 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 rned.** by sqlit
13e60 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 e3_malloc() or s
13e70 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
13e80 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d releases that m
13e90 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 emory so.** that
13ea0 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 it might be reu
13eb0 73 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 sed. The sqlite
13ec0 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 3_free() routine
13ed0 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 is.** a no-op i
13ee0 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 f is called with
13ef0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
13f00 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c Passing a NULL
13f10 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 pointer.** to s
13f20 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 qlite3_free() is
13f30 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 harmless. Afte
13f40 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d r being freed, m
13f50 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 emory.** should
13f60 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 neither be read
13f70 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 nor written. Ev
13f80 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 en reading previ
13f90 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d ously freed.** m
13fa0 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 emory might resu
13fb0 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 lt in a segmenta
13fc0 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 tion fault or ot
13fd0 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 her severe error
13fe0 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 ..** Memory corr
13ff0 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e uption, a segmen
14000 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 tation fault, or
14010 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 other severe er
14020 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 ror.** might res
14030 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 ult if sqlite3_f
14040 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 ree() is called
14050 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 with a non-NULL
14060 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 pointer that.**
14070 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 was not obtained
14080 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 from sqlite3_ma
14090 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 lloc() or sqlite
140a0 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 3_realloc()..**.
140b0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 ** The sqlite3_r
140c0 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 ealloc() interfa
140d0 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 ce attempts to r
140e0 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 esize a.** prior
140f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
14100 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 on to be at leas
14110 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 t N bytes, where
14120 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 N is the.** sec
14130 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 ond parameter.
14140 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 The memory alloc
14150 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 ation to be resi
14160 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74 zed is the first
14170 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 20 .** parameter.
14180 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 If the first par
14190 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
141a0 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 3_realloc().** i
141b0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
141c0 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 then its behavi
141d0 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 or is identical
141e0 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 to calling.** sq
141f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 lite3_malloc(N)
14200 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 where N is the s
14210 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
14220 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c to sqlite3_reall
14230 6f 63 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65 20 oc()..** If the
14240 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
14250 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c to sqlite3_real
14260 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 loc() is zero or
14270 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 .** negative the
14280 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 n the behavior i
14290 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 s exactly the sa
142a0 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a me as calling.**
142b0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 sqlite3_free(P)
142c0 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20 where P is the
142d0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
142e0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c to sqlite3_reall
142f0 6f 63 28 29 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 oc()..** sqlite3
14300 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 _realloc() retur
14310 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
14320 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 a memory allocat
14330 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 ion.** of at lea
14340 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 st N bytes in si
14350 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 ze or NULL if su
14360 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 fficient memory
14370 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a is unavailable..
14380 2a 2a 20 49 66 20 4d 20 69 73 20 74 68 65 20 73 ** If M is the s
14390 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 ize of the prior
143a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 allocation, the
143b0 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 n min(N,M) bytes
143c0 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 .** of the prior
143d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 allocation are
143e0 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 copied into the
143f0 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 beginning of buf
14400 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 fer returned.**
14410 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c by sqlite3_reall
14420 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 oc() and the pri
14430 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 or allocation is
14440 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73 71 freed..** If sq
14450 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 lite3_realloc()
14460 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 returns NULL, th
14470 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c en the prior all
14480 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f ocation.** is no
14490 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 t freed..**.** T
144a0 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e he memory return
144b0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 ed by sqlite3_ma
144c0 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 lloc() and sqlit
144d0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 e3_realloc().**
144e0 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 is always aligne
144f0 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e d to at least an
14500 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 8 byte boundary
14510 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 . {END}.**.** Th
14520 65 20 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d e default implem
14530 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 entation of the
14540 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
14550 6e 20 73 75 62 73 79 73 74 65 6d 20 75 73 65 73 n subsystem uses
14560 0a 2a 2a 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29 .** the malloc()
14570 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 , realloc() and
14580 66 72 65 65 28 29 20 70 72 6f 76 69 64 65 64 20 free() provided
14590 62 79 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 by the standard
145a0 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 7b 48 C library..** {H
145b0 31 37 33 38 32 7d 20 48 6f 77 65 76 65 72 2c 20 17382} However,
145c0 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d if SQLite is com
145d0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a piled with the.*
145e0 2a 20 53 51 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f * SQLITE_MEMORY_
145f0 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 SIZE=<i>NNN</i>
14600 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d C preprocessor m
14610 61 63 72 6f 20 28 77 68 65 72 65 20 3c 69 3e 4e acro (where <i>N
14620 4e 4e 3c 2f 69 3e 0a 2a 2a 20 69 73 20 61 6e 20 NN</i>.** is an
14630 69 6e 74 65 67 65 72 29 2c 20 74 68 65 6e 20 53 integer), then S
14640 51 4c 69 74 65 20 63 72 65 61 74 65 20 61 20 73 QLite create a s
14650 74 61 74 69 63 20 61 72 72 61 79 20 6f 66 20 61 tatic array of a
14660 74 20 6c 65 61 73 74 0a 2a 2a 20 3c 69 3e 4e 4e t least.** <i>NN
14670 4e 3c 2f 69 3e 20 62 79 74 65 73 20 69 6e 20 73 N</i> bytes in s
14680 69 7a 65 20 61 6e 64 20 75 73 65 73 20 74 68 61 ize and uses tha
14690 74 20 61 72 72 61 79 20 66 6f 72 20 61 6c 6c 20 t array for all
146a0 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 0a 2a of its dynamic.*
146b0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 * memory allocat
146c0 69 6f 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44 7d ion needs. {END}
146d0 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d Additional mem
146e0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 70 ory allocator op
146f0 74 69 6f 6e 73 0a 2a 2a 20 6d 61 79 20 62 65 20 tions.** may be
14700 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 added in future
14710 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 releases..**.**
14720 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f In SQLite versio
14730 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e n 3.5.0 and 3.5.
14740 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 1, it was possib
14750 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 le to define.**
14760 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f the SQLITE_OMIT_
14770 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f MEMORY_ALLOCATIO
14780 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 N which would ca
14790 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e use the built-in
147a0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
147b0 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 on of these rout
147c0 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 ines to be omitt
147d0 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 ed. That capabi
147e0 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f lity.** is no lo
147f0 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 nger provided.
14800 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 Only built-in me
14810 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 mory allocators
14820 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a can be used..**.
14830 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f ** The Windows O
14840 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 S interface laye
14850 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 r calls.** the s
14860 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 ystem malloc() a
14870 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74 nd free() direct
14880 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 ly when converti
14890 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 ng.** filenames
148a0 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d between the UTF-
148b0 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 8 encoding used
148c0 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 by SQLite.** and
148d0 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 whatever filena
148e0 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 me encoding is u
148f0 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69 sed by the parti
14900 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a cular Windows.**
14910 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 installation.
14920 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f Memory allocatio
14930 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 65 74 n errors are det
14940 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 ected, but.** th
14950 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 ey are reported
14960 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f back as [SQLITE_
14970 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 CANTOPEN] or.**
14980 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 [SQLITE_IOERR] r
14990 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 ather than [SQLI
149a0 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a TE_NOMEM]..**.**
149b0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
149c0 2a 20 5b 48 31 37 33 30 33 5d 20 5b 48 31 37 33 * [H17303] [H173
149d0 30 34 5d 20 5b 48 31 37 33 30 35 5d 20 5b 48 31 04] [H17305] [H1
149e0 37 33 30 36 5d 20 5b 48 31 37 33 31 30 5d 20 5b 7306] [H17310] [
149f0 48 31 37 33 31 32 5d 20 5b 48 31 37 33 31 35 5d H17312] [H17315]
14a00 20 5b 48 31 37 33 31 38 5d 0a 2a 2a 20 5b 48 31 [H17318].** [H1
14a10 37 33 32 31 5d 20 5b 48 31 37 33 32 32 5d 20 5b 7321] [H17322] [
14a20 48 31 37 33 32 33 5d 0a 2a 2a 0a 2a 2a 20 54 68 H17323].**.** Th
14a30 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 e pointer argume
14a40 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f nts to [sqlite3_
14a50 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c free()] and [sql
14a60 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a ite3_realloc()].
14a70 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 ** must be eithe
14a80 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 r NULL or else p
14a90 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 ointers obtained
14aa0 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a from a prior.**
14ab0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b invocation of [
14ac0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
14ad0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 ] or [sqlite3_re
14ae0 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 alloc()] that ha
14af0 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 ve.** not yet be
14b00 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a en released..**.
14b10 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ** The applicati
14b20 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 on must not read
14b30 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 or write any pa
14b40 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b rt of.** a block
14b50 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 of memory after
14b60 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c it has been rel
14b70 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b eased using.** [
14b80 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 sqlite3_free()]
14b90 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c or [sqlite3_real
14ba0 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 loc()]..*/.SQLIT
14bb0 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 E_API void *sqli
14bc0 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b te3_malloc(int);
14bd0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
14be0 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f *sqlite3_reallo
14bf0 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 c(void*, int);.S
14c00 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
14c10 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 qlite3_free(void
14c20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
14c30 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f REF: Memory Allo
14c40 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 cator Statistics
14c50 20 7b 48 31 37 33 37 30 7d 20 3c 53 33 30 32 31 {H17370} <S3021
14c60 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 0>.**.** SQLite
14c70 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 provides these t
14c80 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f wo interfaces fo
14c90 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 r reporting on t
14ca0 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 he status.** of
14cb0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c the [sqlite3_mal
14cc0 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 loc()], [sqlite3
14cd0 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 _free()], and [s
14ce0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
14cf0 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 ].** routines, w
14d00 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 hich form the bu
14d10 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c ilt-in memory al
14d20 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 location subsyst
14d30 65 6d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 em..**.** Requir
14d40 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 ements:.** [H173
14d50 37 31 5d 20 5b 48 31 37 33 37 33 5d 20 5b 48 31 71] [H17373] [H1
14d60 37 33 37 34 5d 20 5b 48 31 37 33 37 35 5d 0a 2a 7374] [H17375].*
14d70 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c /.SQLITE_API sql
14d80 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 ite3_int64 sqlit
14d90 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 e3_memory_used(v
14da0 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 oid);.SQLITE_API
14db0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 sqlite3_int64 s
14dc0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
14dd0 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 ghwater(int rese
14de0 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 tFlag);../*.** C
14df0 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d API3REF: Pseudo-
14e00 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 Random Number Ge
14e10 6e 65 72 61 74 6f 72 20 7b 48 31 37 33 39 30 7d nerator {H17390}
14e20 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S20000>.**.**
14e30 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 SQLite contains
14e40 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 a high-quality p
14e50 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d seudo-random num
14e60 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 ber generator (P
14e70 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 RNG) used to.**
14e80 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 select random [R
14e90 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 OWID | ROWIDs] w
14ea0 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 hen inserting ne
14eb0 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 w records into a
14ec0 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 table that.** a
14ed0 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20 lready uses the
14ee0 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 largest possible
14ef0 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 [ROWID]. The P
14f00 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 RNG is also used
14f10 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c for.** the buil
14f20 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e d-in random() an
14f30 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 d randomblob() S
14f40 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 QL functions. T
14f50 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c his interface al
14f60 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 lows.** applicat
14f70 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 ions to access t
14f80 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 he same PRNG for
14f90 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e other purposes.
14fa0 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f .**.** A call to
14fb0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 this routine st
14fc0 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 ores N bytes of
14fd0 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 randomness into
14fe0 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 buffer P..**.**
14ff0 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 The first time t
15000 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 his routine is i
15010 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 nvoked (either i
15020 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a nternally or by.
15030 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ** the applicati
15040 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 on) the PRNG is
15050 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e seeded using ran
15060 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 domness obtained
15070 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 .** from the xRa
15080 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 ndomness method
15090 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b of the default [
150a0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a sqlite3_vfs] obj
150b0 65 63 74 2e 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73 ect..** On all s
150c0 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 ubsequent invoca
150d0 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 tions, the pseud
150e0 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 o-randomness is
150f0 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 generated.** int
15100 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 ernally and with
15110 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 out recourse to
15120 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 the [sqlite3_vfs
15130 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a ] xRandomness.**
15140 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 52 method..**.** R
15150 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
15160 5b 48 31 37 33 39 32 5d 0a 2a 2f 0a 53 51 4c 49 [H17392].*/.SQLI
15170 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 TE_API void sqli
15180 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 te3_randomness(i
15190 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a nt N, void *P);.
151a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
151b0 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 Compile-Time Au
151c0 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c thorization Call
151d0 62 61 63 6b 73 20 7b 48 31 32 35 30 30 7d 20 3c backs {H12500} <
151e0 53 37 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S70100>.**.** Th
151f0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 is routine regis
15200 74 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65 ters a authorize
15210 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 r callback with
15220 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 a particular.**
15230 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
15240 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 tion], supplied
15250 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 in the first arg
15260 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 61 75 ument..** The au
15270 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
15280 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 k is invoked as
15290 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 SQL statements a
152a0 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 re being compile
152b0 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 d.** by [sqlite3
152c0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 _prepare()] or i
152d0 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c ts variants [sql
152e0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
152f0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
15300 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 prepare16()] and
15310 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
15320 65 31 36 5f 76 32 28 29 5d 2e 20 20 41 74 20 76 e16_v2()]. At v
15330 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 arious.** points
15340 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 during the comp
15350 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c ilation process,
15360 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 as logic is bei
15370 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f ng created.** to
15380 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 perform various
15390 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 actions, the au
153a0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
153b0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a k is invoked to.
153c0 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 ** see if those
153d0 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f actions are allo
153e0 77 65 64 2e 20 20 54 68 65 20 61 75 74 68 6f 72 wed. The author
153f0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 izer callback sh
15400 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b ould.** return [
15410 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c SQLITE_OK] to al
15420 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 low the action,
15430 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 [SQLITE_IGNORE]
15440 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a to disallow the.
15450 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 ** specific acti
15460 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 on but allow the
15470 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
15480 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 o continue to be
15490 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 .** compiled, or
154a0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 [SQLITE_DENY] t
154b0 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 o cause the enti
154c0 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 re SQL statement
154d0 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 to be.** reject
154e0 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 ed with an error
154f0 2e 20 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 . If the author
15500 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 izer callback re
15510 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c turns.** any val
15520 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 ue other than [S
15530 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b QLITE_IGNORE], [
15540 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b SQLITE_OK], or [
15550 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 SQLITE_DENY].**
15560 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 then the [sqlite
15570 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
15580 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 or equivalent ca
15590 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 ll that triggere
155a0 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 d.** the authori
155b0 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 zer will fail wi
155c0 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 th an error mess
155d0 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 age..**.** When
155e0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 the callback ret
155f0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d urns [SQLITE_OK]
15600 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 , that means the
15610 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 operation.** re
15620 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 quested is ok.
15630 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 When the callbac
15640 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 k returns [SQLIT
15650 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 E_DENY], the.**
15660 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
15670 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 _v2()] or equiva
15680 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 lent call that t
15690 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 riggered the.**
156a0 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 authorizer will
156b0 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 fail with an err
156c0 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 or message expla
156d0 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 ining that.** ac
156e0 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 cess is denied.
156f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 .**.** The first
15700 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
15710 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
15720 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 lback is a copy
15730 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 of the third.**
15740 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
15750 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 sqlite3_set_aut
15760 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 horizer() interf
15770 61 63 65 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 ace. The second
15780 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 parameter.** to
15790 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 the callback is
157a0 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 an integer [SQLI
157b0 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e TE_COPY | action
157c0 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 code] that spec
157d0 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 ifies.** the par
157e0 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 ticular action t
157f0 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e o be authorized.
15800 20 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 The third throu
15810 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 gh sixth paramet
15820 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 ers.** to the ca
15830 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d llback are zero-
15840 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e terminated strin
15850 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 gs that contain
15860 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 additional.** de
15870 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 tails about the
15880 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 action to be aut
15890 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 horized..**.** I
158a0 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 f the action cod
158b0 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 e is [SQLITE_REA
158c0 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 D].** and the ca
158d0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b llback returns [
158e0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 SQLITE_IGNORE] t
158f0 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 hen the.** [prep
15900 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
15910 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e statement is con
15920 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 structed to subs
15930 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c titute.** a NULL
15940 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 value in place
15950 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c of the table col
15960 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 umn that would h
15970 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 ave.** been read
15980 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 if [SQLITE_OK]
15990 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 had been returne
159a0 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f d. The [SQLITE_
159b0 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 IGNORE].** retur
159c0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f n can be used to
159d0 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 deny an untrust
159e0 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 ed user access t
159f0 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 o individual.**
15a00 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 columns of a tab
15a10 6c 65 2e 0a 2a 2a 20 49 66 20 74 68 65 20 61 63 le..** If the ac
15a20 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 tion code is [SQ
15a30 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 LITE_DELETE] and
15a40 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 the callback re
15a50 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 turns.** [SQLITE
15a60 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 _IGNORE] then th
15a70 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 e [DELETE] opera
15a80 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 tion proceeds bu
15a90 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 t the.** [trunca
15aa0 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d te optimization]
15ab0 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 is disabled and
15ac0 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 all rows are de
15ad0 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c leted individual
15ae0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 ly..**.** An aut
15af0 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 horizer is used
15b00 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 when [sqlite3_pr
15b10 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e epare | preparin
15b20 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d g].** SQL statem
15b30 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 ents from an unt
15b40 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 rusted source, t
15b50 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 o ensure that th
15b60 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 e SQL statements
15b70 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 .** do not try t
15b80 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 o access data th
15b90 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 ey are not allow
15ba0 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 ed to see, or th
15bb0 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a at they do not.*
15bc0 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 * try to execute
15bd0 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 malicious state
15be0 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 ments that damag
15bf0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 e the database.
15c00 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c For.** example,
15c10 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 an application
15c20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 may allow a user
15c30 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 to enter arbitr
15c40 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 ary.** SQL queri
15c50 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f es for evaluatio
15c60 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e n by a database.
15c70 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 But the applic
15c80 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f ation does.** no
15c90 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 t want the user
15ca0 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 to be able to ma
15cb0 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 ke arbitrary cha
15cc0 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 nges to the.** d
15cd0 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 atabase. An aut
15ce0 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 horizer could th
15cf0 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 en be put in pla
15d00 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 ce while the.**
15d10 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c user-entered SQL
15d20 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 is being [sqlit
15d30 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 e3_prepare | pre
15d40 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 pared] that.** d
15d50 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 isallows everyth
15d60 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 ing except [SELE
15d70 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a CT] statements..
15d80 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f **.** Applicatio
15d90 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 ns that need to
15da0 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d process SQL from
15db0 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 untrusted sourc
15dc0 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f es.** might also
15dd0 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 consider loweri
15de0 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 ng resource limi
15df0 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ts using [sqlite
15e00 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 3_limit()].** an
15e10 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 d limiting datab
15e20 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 ase size using t
15e30 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 he [max_page_cou
15e40 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 nt] [PRAGMA].**
15e50 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 in addition to u
15e60 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a sing an authoriz
15e70 65 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 er..**.** Only a
15e80 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a single authoriz
15e90 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 er can be in pla
15ea0 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 ce on a database
15eb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 connection.** a
15ec0 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 t a time. Each
15ed0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
15ee0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f set_authorizer o
15ef0 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 verrides the.**
15f00 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 20 20 previous call.
15f10 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 Disable the auth
15f20 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c orizer by instal
15f30 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c ling a NULL call
15f40 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 back..** The aut
15f50 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 horizer is disab
15f60 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a led by default..
15f70 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 **.** The author
15f80 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 izer callback mu
15f90 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 st not do anythi
15fa0 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 ng that will mod
15fb0 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 ify.** the datab
15fc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 ase connection t
15fd0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 hat invoked the
15fe0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
15ff0 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ack..** Note tha
16000 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 t [sqlite3_prepa
16010 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 re_v2()] and [sq
16020 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f lite3_step()] bo
16030 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a th modify their.
16040 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ** database conn
16050 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 ections for the
16060 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 meaning of "modi
16070 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 fy" in this para
16080 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 graph..**.** Whe
16090 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 n [sqlite3_prepa
160a0 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 re_v2()] is used
160b0 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 to prepare a st
160c0 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 atement, the.**
160d0 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 statement might
160e0 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 be re-prepared d
160f0 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 uring [sqlite3_s
16100 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 tep()] due to a
16110 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 .** schema chang
16120 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 e. Hence, the a
16130 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
16140 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 d ensure that th
16150 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 e.** correct aut
16160 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
16170 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 remains in plac
16180 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 e during the [sq
16190 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a lite3_step()]..*
161a0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 *.** Note that t
161b0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
161c0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
161d0 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a d only during.**
161e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
161f0 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 e()] or its vari
16200 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 ants. Authoriza
16210 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 tion is not.** p
16220 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 erformed during
16230 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 statement evalua
16240 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 tion in [sqlite3
16250 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 _step()], unless
16260 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e .** as stated in
16270 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 the previous pa
16280 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 ragraph, sqlite3
16290 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a _step() invokes.
162a0 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 ** sqlite3_prepa
162b0 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 re_v2() to repre
162c0 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 pare a statement
162d0 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 after a schema
162e0 63 68 61 6e 67 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 change..**.** Re
162f0 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
16300 48 31 32 35 30 31 5d 20 5b 48 31 32 35 30 32 5d H12501] [H12502]
16310 20 5b 48 31 32 35 30 33 5d 20 5b 48 31 32 35 30 [H12503] [H1250
16320 34 5d 20 5b 48 31 32 35 30 35 5d 20 5b 48 31 32 4] [H12505] [H12
16330 35 30 36 5d 20 5b 48 31 32 35 30 37 5d 20 5b 48 506] [H12507] [H
16340 31 32 35 31 30 5d 0a 2a 2a 20 5b 48 31 32 35 31 12510].** [H1251
16350 31 5d 20 5b 48 31 32 35 31 32 5d 20 5b 48 31 32 1] [H12512] [H12
16360 35 32 30 5d 20 5b 48 31 32 35 32 31 5d 20 5b 48 520] [H12521] [H
16370 31 32 35 32 32 5d 0a 2a 2f 0a 53 51 4c 49 54 45 12522].*/.SQLITE
16380 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
16390 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 _set_authorizer(
163a0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 . sqlite3*,. i
163b0 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 nt (*xAuth)(void
163c0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 *,int,const char
163d0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f *,const char*,co
163e0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 nst char*,const
163f0 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a char*),. void *
16400 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a pUserData.);../*
16410 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 .** CAPI3REF: Au
16420 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 thorizer Return
16430 43 6f 64 65 73 20 7b 48 31 32 35 39 30 7d 20 3c Codes {H12590} <
16440 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 H12500>.**.** Th
16450 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 e [sqlite3_set_a
16460 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 uthorizer | auth
16470 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
16480 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a function] must.*
16490 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 * return either
164a0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f [SQLITE_OK] or o
164b0 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 ne of these two
164c0 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 constants in ord
164d0 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 er.** to signal
164e0 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f SQLite whether o
164f0 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e r not the action
16500 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 is permitted.
16510 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 See the.** [sqli
16520 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
16530 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 er | authorizer
16540 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 documentation] f
16550 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a or additional.**
16560 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f information..*/
16570 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
16580 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 DENY 1 /* Ab
16590 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 ort the SQL stat
165a0 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 ement with an er
165b0 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ror */.#define S
165c0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 QLITE_IGNORE 2
165d0 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 /* Don't allow
165e0 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 access, but don'
165f0 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 t generate an er
16600 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 ror */../*.** CA
16610 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a PI3REF: Authoriz
16620 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 20 er Action Codes
16630 7b 48 31 32 35 35 30 7d 20 3c 48 31 32 35 30 30 {H12550} <H12500
16640 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c >.**.** The [sql
16650 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
16660 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 zer()] interface
16670 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c registers a cal
16680 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a lback function.*
16690 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 * that is invoke
166a0 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 d to authorize c
166b0 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 ertain SQL state
166c0 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 ment actions. T
166d0 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 he.** second par
166e0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 ameter to the ca
166f0 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 llback is an int
16700 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 eger code that s
16710 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 pecifies.** what
16720 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 action is being
16730 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 authorized. Th
16740 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 ese are the inte
16750 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 ger action codes
16760 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 that.** the aut
16770 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
16780 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a may be passed..
16790 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 **.** These acti
167a0 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 on code values s
167b0 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 ignify what kind
167c0 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 of operation is
167d0 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 to be.** author
167e0 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 ized. The 3rd a
167f0 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 nd 4th parameter
16800 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 s to the authori
16810 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 zation.** callba
16820 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c ck function will
16830 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f be parameters o
16840 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 r NULL depending
16850 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 on which of the
16860 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 se.** codes is u
16870 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e sed as the secon
16880 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 d parameter. Th
16890 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 5th parameter
168a0 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 to the.** author
168b0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 izer callback is
168c0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
168d0 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e database ("main
168e0 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 ", "temp",.** et
168f0 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c c.) if applicabl
16900 65 2e 20 20 54 68 65 20 36 74 68 20 70 61 72 61 e. The 6th para
16910 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 meter to the aut
16920 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
16930 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 .** is the name
16940 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 of the inner-mos
16950 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 t trigger or vie
16960 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e w that is respon
16970 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 sible for.** the
16980 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 access attempt
16990 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 or NULL if this
169a0 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 access attempt i
169b0 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a s directly from.
169c0 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c ** top-level SQL
169d0 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 code..**.** Req
169e0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 uirements:.** [H
169f0 31 32 35 35 31 5d 20 5b 48 31 32 35 35 32 5d 20 12551] [H12552]
16a00 5b 48 31 32 35 35 33 5d 20 5b 48 31 32 35 35 34 [H12553] [H12554
16a10 5d 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ].*/./**********
16a20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
16a30 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
16a40 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a * 3rd **********
16a50 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a ** 4th *********
16a60 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 **/.#define SQLI
16a70 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 TE_CREATE_INDEX
16a80 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 1 /*
16a90 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 Index Name
16aa0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
16ab0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
16ac0 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 E_CREATE_TABLE
16ad0 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 2 /* T
16ae0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e able Name N
16af0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
16b00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
16b10 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 _CREATE_TEMP_IND
16b20 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e EX 3 /* In
16b30 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 dex Name Ta
16b40 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
16b50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
16b60 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c CREATE_TEMP_TABL
16b70 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 E 4 /* Tab
16b80 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
16b90 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
16ba0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
16bb0 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 REATE_TEMP_TRIGG
16bc0 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 ER 5 /* Trig
16bd0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c ger Name Tabl
16be0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
16bf0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
16c00 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 EATE_TEMP_VIEW
16c10 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 6 /* View
16c20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
16c30 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
16c40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
16c50 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 ATE_TRIGGER
16c60 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 7 /* Trigge
16c70 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 r Name Table
16c80 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
16c90 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
16ca0 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 TE_VIEW
16cb0 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 8 /* View Na
16cc0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 me NULL
16cd0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
16ce0 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 ine SQLITE_DELET
16cf0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 E
16d00 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 9 /* Table Na
16d10 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
16d20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
16d30 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 ne SQLITE_DROP_I
16d40 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31 NDEX 1
16d50 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 0 /* Index Nam
16d60 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d e Table Nam
16d70 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
16d80 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 e SQLITE_DROP_TA
16d90 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31 BLE 11
16da0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
16db0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
16dc0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
16dd0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d SQLITE_DROP_TEM
16de0 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 P_INDEX 12
16df0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 /* Index Name
16e00 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 Table Name
16e10 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
16e20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 SQLITE_DROP_TEMP
16e30 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 _TABLE 13
16e40 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
16e50 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
16e60 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
16e70 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f QLITE_DROP_TEMP_
16e80 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20 TRIGGER 14
16e90 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 /* Trigger Name
16ea0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
16eb0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
16ec0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 LITE_DROP_TEMP_V
16ed0 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f IEW 15 /
16ee0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 * View Name
16ef0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
16f00 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
16f10 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 ITE_DROP_TRIGGER
16f20 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 16 /*
16f30 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 Trigger Name
16f40 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
16f50 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
16f60 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 TE_DROP_VIEW
16f70 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 17 /*
16f80 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 View Name
16f90 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
16fa0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
16fb0 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 E_INSERT
16fc0 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 18 /* T
16fd0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e able Name N
16fe0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
16ff0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
17000 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 _PRAGMA
17010 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 19 /* Pr
17020 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 agma Name 1s
17030 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f t arg or NULL */
17040 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
17050 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 READ
17060 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 20 /* Tab
17070 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c le Name Col
17080 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a umn Name */.
17090 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
170a0 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 ELECT
170b0 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 21 /* NULL
170c0 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c NULL
170d0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
170e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 define SQLITE_TR
170f0 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 ANSACTION
17100 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 22 /* Opera
17110 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 tion NULL
17120 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
17130 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 efine SQLITE_UPD
17140 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 ATE
17150 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 23 /* Table
17160 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e Name Column
17170 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
17180 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 fine SQLITE_ATTA
17190 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 CH
171a0 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 24 /* Filenam
171b0 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 e NULL
171c0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
171d0 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 ine SQLITE_DETAC
171e0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 H
171f0 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 25 /* Database
17200 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 Name NULL
17210 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
17220 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f ne SQLITE_ALTER_
17230 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 TABLE 2
17240 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6 /* Database
17250 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d Name Table Nam
17260 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
17270 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 e SQLITE_REINDEX
17280 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37 27
17290 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 /* Index Name
172a0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
172b0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
172c0 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 SQLITE_ANALYZE
172d0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20 28
172e0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
172f0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
17300 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
17310 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 SQLITE_CREATE_VT
17320 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 ABLE 29
17330 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
17340 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 Module Name
17350 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
17360 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c QLITE_DROP_VTABL
17370 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20 E 30
17380 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
17390 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 Module Name
173a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
173b0 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 LITE_FUNCTION
173c0 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 31 /
173d0 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 * NULL
173e0 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 Function Name
173f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
17400 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 ITE_SAVEPOINT
17410 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 32 /*
17420 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 Operation
17430 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 Savepoint Name
17440 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
17450 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 TE_COPY
17460 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 0 /*
17470 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a No longer used *
17480 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 /../*.** CAPI3RE
17490 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 F: Tracing And P
174a0 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f rofiling Functio
174b0 6e 73 20 7b 48 31 32 32 38 30 7d 20 3c 53 36 30 ns {H12280} <S60
174c0 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 400>.** EXPERIME
174d0 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 NTAL.**.** These
174e0 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 routines regist
174f0 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 er callback func
17500 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 tions that can b
17510 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 e used for.** tr
17520 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c acing and profil
17530 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f ing the executio
17540 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 n of SQL stateme
17550 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 nts..**.** The c
17560 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
17570 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 registered by s
17580 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 qlite3_trace() i
17590 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 s invoked at.**
175a0 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 various times wh
175b0 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d en an SQL statem
175c0 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e ent is being run
175d0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 by [sqlite3_ste
175e0 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 63 61 6c p()]..** The cal
175f0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 lback returns a
17600 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 UTF-8 rendering
17610 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 of the SQL state
17620 6d 65 6e 74 20 74 65 78 74 0a 2a 2a 20 61 73 20 ment text.** as
17630 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 the statement fi
17640 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 rst begins execu
17650 74 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 ting. Additiona
17660 6c 20 63 61 6c 6c 62 61 63 6b 73 20 6f 63 63 75 l callbacks occu
17670 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 r.** as each tri
17680 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 ggered subprogra
17690 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 m is entered. T
176a0 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 he callbacks for
176b0 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e triggers.** con
176c0 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c tain a UTF-8 SQL
176d0 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 comment that id
176e0 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 entifies the tri
176f0 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 gger..**.** The
17700 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
17710 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 n registered by
17720 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 sqlite3_profile(
17730 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 ) is invoked.**
17740 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 as each SQL stat
17750 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 ement finishes.
17760 20 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c The profile cal
17770 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a lback contains.*
17780 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 * the original s
17790 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e tatement text an
177a0 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 d an estimate of
177b0 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 wall-clock time
177c0 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 .** of how long
177d0 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 that statement t
177e0 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a ook to run..**.*
177f0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
17800 2a 2a 20 5b 48 31 32 32 38 31 5d 20 5b 48 31 32 ** [H12281] [H12
17810 32 38 32 5d 20 5b 48 31 32 32 38 33 5d 20 5b 48 282] [H12283] [H
17820 31 32 32 38 34 5d 20 5b 48 31 32 32 38 35 5d 20 12284] [H12285]
17830 5b 48 31 32 32 38 37 5d 20 5b 48 31 32 32 38 38 [H12287] [H12288
17840 5d 20 5b 48 31 32 32 38 39 5d 0a 2a 2a 20 5b 48 ] [H12289].** [H
17850 31 32 32 39 30 5d 0a 2a 2f 0a 53 51 4c 49 54 45 12290].*/.SQLITE
17860 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 _API SQLITE_EXPE
17870 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 RIMENTAL void *s
17880 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c qlite3_trace(sql
17890 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 ite3*, void(*xTr
178a0 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 ace)(void*,const
178b0 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b char*), void*);
178c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 .SQLITE_API SQLI
178d0 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 TE_EXPERIMENTAL
178e0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 void *sqlite3_pr
178f0 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a ofile(sqlite3*,.
17900 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c void(*xProfil
17910 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 e)(void*,const c
17920 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e har*,sqlite3_uin
17930 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f t64), void*);../
17940 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 *.** CAPI3REF: Q
17950 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 uery Progress Ca
17960 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 31 30 7d llbacks {H12910}
17970 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S60400>.**.**
17980 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e This routine con
17990 66 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62 61 figures a callba
179a0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68 ck function - th
179b0 65 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20 63 61 e.** progress ca
179c0 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74 20 69 73 llback - that is
179d0 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 invoked periodi
179e0 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e cally during lon
179f0 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61 6c g.** running cal
17a00 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 ls to [sqlite3_e
17a10 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 xec()], [sqlite3
17a20 5f 73 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 _step()] and.**
17a30 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 [sqlite3_get_tab
17a40 6c 65 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d 70 le()]. An examp
17a50 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a le use for this.
17a60 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 ** interface is
17a70 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 to keep a GUI up
17a80 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c dated during a l
17a90 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a arge query..**.*
17aa0 2a 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 * If the progres
17ab0 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 s callback retur
17ac0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 ns non-zero, the
17ad0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a operation is.**
17ae0 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 interrupted. T
17af0 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 his feature can
17b00 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 be used to imple
17b10 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 ment a.** "Cance
17b20 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 l" button on a G
17b30 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c UI progress dial
17b40 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 og box..**.** Th
17b50 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c e progress handl
17b60 65 72 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 er must not do a
17b70 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c nything that wil
17b80 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 l modify.** the
17b90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
17ba0 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 ion that invoked
17bb0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 the progress ha
17bc0 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 ndler..** Note t
17bd0 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 hat [sqlite3_pre
17be0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b pare_v2()] and [
17bf0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
17c00 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 both modify thei
17c10 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f r.** database co
17c20 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 nnections for th
17c30 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f e meaning of "mo
17c40 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 dify" in this pa
17c50 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 52 ragraph..**.** R
17c60 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
17c70 5b 48 31 32 39 31 31 5d 20 5b 48 31 32 39 31 32 [H12911] [H12912
17c80 5d 20 5b 48 31 32 39 31 33 5d 20 5b 48 31 32 39 ] [H12913] [H129
17c90 31 34 5d 20 5b 48 31 32 39 31 35 5d 20 5b 48 31 14] [H12915] [H1
17ca0 32 39 31 36 5d 20 5b 48 31 32 39 31 37 5d 20 5b 2916] [H12917] [
17cb0 48 31 32 39 31 38 5d 0a 2a 2a 0a 2a 2f 0a 53 51 H12918].**.*/.SQ
17cc0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 LITE_API void sq
17cd0 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 lite3_progress_h
17ce0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c andler(sqlite3*,
17cf0 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 int, int(*)(voi
17d00 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a d*), void*);../*
17d10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 .** CAPI3REF: Op
17d20 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 ening A New Data
17d30 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 base Connection
17d40 7b 48 31 32 37 30 30 7d 20 3c 53 34 30 32 30 30 {H12700} <S40200
17d50 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f >.**.** These ro
17d60 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 utines open an S
17d70 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 QLite database f
17d80 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20 69 ile whose name i
17d90 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a 2a s given by the.*
17da0 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d * filename argum
17db0 65 6e 74 2e 20 54 68 65 20 66 69 6c 65 6e 61 6d ent. The filenam
17dc0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e e argument is in
17dd0 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 terpreted as UTF
17de0 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 -8 for.** sqlite
17df0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 3_open() and sql
17e00 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 ite3_open_v2() a
17e10 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 nd as UTF-16 in
17e20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a the native byte.
17e30 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c ** order for sql
17e40 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 41 ite3_open16(). A
17e50 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
17e60 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 ction] handle is
17e70 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 usually.** retu
17e80 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 rned in *ppDb, e
17e90 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 ven if an error
17ea0 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c occurs. The onl
17eb0 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 y exception is t
17ec0 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 hat.** if SQLite
17ed0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c is unable to al
17ee0 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f locate memory to
17ef0 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 hold the [sqlit
17f00 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 e3] object,.** a
17f10 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 NULL will be wr
17f20 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 itten into *ppDb
17f30 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f instead of a po
17f40 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 inter to the [sq
17f50 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 lite3].** object
17f60 2e 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 . If the databas
17f70 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 e is opened (and
17f80 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63 /or created) suc
17f90 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a cessfully, then.
17fa0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 ** [SQLITE_OK] i
17fb0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 s returned. Oth
17fc0 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 erwise an [error
17fd0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e code] is return
17fe0 65 64 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c ed. The.** [sql
17ff0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f ite3_errmsg()] o
18000 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 r [sqlite3_errms
18010 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 g16()] routines
18020 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f can be used to o
18030 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c btain.** an Engl
18040 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 ish language des
18050 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 cription of the
18060 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 error..**.** The
18070 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e default encodin
18080 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 g for the databa
18090 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 se will be UTF-8
180a0 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f if.** sqlite3_o
180b0 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 pen() or sqlite3
180c0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61 _open_v2() is ca
180d0 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d lled and.** UTF-
180e0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 16 in the native
180f0 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 73 byte order if s
18100 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 qlite3_open16()
18110 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 is used..**.** W
18120 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e hether or not an
18130 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 error occurs wh
18140 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c en it is opened,
18150 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 resources.** as
18160 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 sociated with th
18170 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
18180 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 ection] handle s
18190 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 hould be release
181a0 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 d by.** passing
181b0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 it to [sqlite3_c
181c0 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 lose()] when it
181d0 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 is no longer req
181e0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 uired..**.** The
181f0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
18200 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 () interface wor
18210 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f ks like sqlite3_
18220 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 open().** except
18230 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73 that it accepts
18240 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 two additional
18250 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 parameters for a
18260 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f dditional contro
18270 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 l.** over the ne
18280 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 w database conne
18290 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61 67 ction. The flag
182a0 73 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 s parameter can
182b0 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 take one of.** t
182c0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 he following thr
182d0 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f ee values, optio
182e0 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 nally combined w
182f0 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c ith the .** [SQL
18300 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 ITE_OPEN_NOMUTEX
18310 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ], [SQLITE_OPEN_
18320 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c FULLMUTEX], [SQL
18330 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 ITE_OPEN_SHAREDC
18340 41 43 48 45 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 ACHE],.** and/or
18350 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 [SQLITE_OPEN_PR
18360 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 IVATECACHE] flag
18370 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a s:.**.** <dl>.**
18380 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 <dt>[SQLITE_OPE
18390 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e N_READONLY]</dt>
183a0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 .** <dd>The data
183b0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 base is opened i
183c0 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 n read-only mode
183d0 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61 . If the databa
183e0 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 se does not.** a
183f0 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e lready exist, an
18400 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e error is return
18410 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c ed.</dd>.**.** <
18420 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f dt>[SQLITE_OPEN_
18430 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a READWRITE]</dt>.
18440 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 ** <dd>The datab
18450 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f ase is opened fo
18460 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 r reading and wr
18470 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c iting if possibl
18480 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a e, or reading.**
18490 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c only if the fil
184a0 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 e is write prote
184b0 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 cted by the oper
184c0 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 ating system. I
184d0 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 n either.** case
184e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 the database mu
184f0 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 st already exist
18500 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 , otherwise an e
18510 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 rror is returned
18520 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
18530 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 >[SQLITE_OPEN_RE
18540 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 ADWRITE] | [SQLI
18550 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c TE_OPEN_CREATE]<
18560 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
18570 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e database is open
18580 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 ed for reading a
18590 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 nd writing, and
185a0 69 73 20 63 72 65 61 74 65 73 20 69 74 20 69 66 is creates it if
185b0 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 .** it does not
185c0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 already exist. T
185d0 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76 his is the behav
185e0 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 ior that is alwa
185f0 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 ys used for.** s
18600 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e qlite3_open() an
18610 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 d sqlite3_open16
18620 28 29 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c ().</dd>.** </dl
18630 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 >.**.** If the 3
18640 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
18650 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
18660 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 ) is not one of
18670 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 the.** combinati
18680 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 ons shown above
18690 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f or one of the co
186a0 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e mbinations shown
186b0 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e 65 64 0a above combined.
186c0 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c ** with the [SQL
186d0 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 ITE_OPEN_NOMUTEX
186e0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ], [SQLITE_OPEN_
186f0 46 55 4c 4c 4d 55 54 45 58 5d 2c 0a 2a 2a 20 5b FULLMUTEX],.** [
18700 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 SQLITE_OPEN_SHAR
18710 45 44 43 41 43 48 45 5d 20 61 6e 64 2f 6f 72 20 EDCACHE] and/or
18720 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 [SQLITE_OPEN_SHA
18730 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 73 2c REDCACHE] flags,
18740 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 .** then the beh
18750 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e avior is undefin
18760 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 ed..**.** If the
18770 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f [SQLITE_OPEN_NO
18780 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 MUTEX] flag is s
18790 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 et, then the dat
187a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
187b0 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 .** opens in the
187c0 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 multi-thread [t
187d0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 hreading mode] a
187e0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 s long as the si
187f0 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d ngle-thread.** m
18800 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e ode has not been
18810 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d set at compile-
18820 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 time or start-ti
18830 6d 65 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 5b me. If the.** [
18840 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c SQLITE_OPEN_FULL
18850 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 MUTEX] flag is s
18860 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 et then the data
18870 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
18880 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 opens.** in the
18890 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 serialized [thre
188a0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 ading mode] unle
188b0 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 ss single-thread
188c0 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 was.** previous
188d0 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 ly selected at c
188e0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 ompile-time or s
188f0 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 54 68 tart-time..** Th
18900 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 e [SQLITE_OPEN_S
18910 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 HAREDCACHE] flag
18920 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 causes the data
18930 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
18940 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c to be.** eligibl
18950 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 e to use [shared
18960 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 cache mode], re
18970 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 gardless of whet
18980 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 her or not share
18990 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e d.** cache is en
189a0 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c abled using [sql
189b0 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 ite3_enable_shar
189c0 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 54 68 ed_cache()]. Th
189d0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 e.** [SQLITE_OPE
189e0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 N_PRIVATECACHE]
189f0 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 flag causes the
18a00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
18a10 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 ion to not.** pa
18a20 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 rticipate in [sh
18a30 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d ared cache mode]
18a40 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 even if it is e
18a50 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 nabled..**.** If
18a60 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 the filename is
18a70 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 ":memory:", the
18a80 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d n a private, tem
18a90 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 porary in-memory
18aa0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 database.** is
18ab0 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 created for the
18ac0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69 connection. Thi
18ad0 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 s in-memory data
18ae0 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 base will vanish
18af0 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 when.** the dat
18b00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
18b10 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 is closed. Fut
18b20 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 ure versions of
18b30 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 SQLite might.**
18b40 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 make use of addi
18b50 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 tional special f
18b60 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 ilenames that be
18b70 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 gin with the ":"
18b80 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 character..** I
18b90 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 t is recommended
18ba0 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 that when a dat
18bb0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 abase filename a
18bc0 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 ctually does beg
18bd0 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 in with.** a ":"
18be0 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 character you s
18bf0 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 hould prefix the
18c00 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 filename with a
18c10 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 pathname such a
18c20 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f s.** "./" to avo
18c30 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a id ambiguity..**
18c40 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e .** If the filen
18c50 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 ame is an empty
18c60 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 string, then a p
18c70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 rivate, temporar
18c80 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 y.** on-disk dat
18c90 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 abase will be cr
18ca0 65 61 74 65 64 2e 20 20 54 68 69 73 20 70 72 69 eated. This pri
18cb0 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 vate database wi
18cc0 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 ll be.** automat
18cd0 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 ically deleted a
18ce0 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 s soon as the da
18cf0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
18d00 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a n is closed..**.
18d10 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 ** The fourth pa
18d20 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
18d30 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 e3_open_v2() is
18d40 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a the name of the.
18d50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d ** [sqlite3_vfs]
18d60 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 object that def
18d70 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 ines the operati
18d80 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 ng system interf
18d90 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 ace that.** the
18da0 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e new database con
18db0 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 nection should u
18dc0 73 65 2e 20 20 49 66 20 74 68 65 20 66 6f 75 72 se. If the four
18dd0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a th parameter is.
18de0 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ** a NULL pointe
18df0 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 r then the defau
18e00 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d lt [sqlite3_vfs]
18e10 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e object is used.
18e20 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 .**.** <b>Note t
18e30 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a o Windows users:
18e40 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 </b> The encodi
18e50 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 ng used for the
18e60 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e filename argumen
18e70 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f t.** of sqlite3_
18e80 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 open() and sqlit
18e90 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 e3_open_v2() mus
18ea0 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 t be UTF-8, not
18eb0 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 whatever.** code
18ec0 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c page is currentl
18ed0 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 y defined. File
18ee0 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 names containing
18ef0 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a international.*
18f00 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 * characters mus
18f10 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 t be converted t
18f20 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f o UTF-8 prior to
18f30 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e passing them in
18f40 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 to.** sqlite3_op
18f50 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f en() or sqlite3_
18f60 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a open_v2()..**.**
18f70 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
18f80 2a 20 5b 48 31 32 37 30 31 5d 20 5b 48 31 32 37 * [H12701] [H127
18f90 30 32 5d 20 5b 48 31 32 37 30 33 5d 20 5b 48 31 02] [H12703] [H1
18fa0 32 37 30 34 5d 20 5b 48 31 32 37 30 36 5d 20 5b 2704] [H12706] [
18fb0 48 31 32 37 30 37 5d 20 5b 48 31 32 37 30 39 5d H12707] [H12709]
18fc0 20 5b 48 31 32 37 31 31 5d 0a 2a 2a 20 5b 48 31 [H12711].** [H1
18fd0 32 37 31 32 5d 20 5b 48 31 32 37 31 33 5d 20 5b 2712] [H12713] [
18fe0 48 31 32 37 31 34 5d 20 5b 48 31 32 37 31 37 5d H12714] [H12717]
18ff0 20 5b 48 31 32 37 31 39 5d 20 5b 48 31 32 37 32 [H12719] [H1272
19000 31 5d 20 5b 48 31 32 37 32 33 5d 0a 2a 2f 0a 53 1] [H12723].*/.S
19010 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
19020 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f lite3_open(. co
19030 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 nst char *filena
19040 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 me, /* Databas
19050 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d e filename (UTF-
19060 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 8) */. sqlite3
19070 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 **ppDb
19080 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 /* OUT: SQLite d
19090 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 b handle */.);.S
190a0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
190b0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 lite3_open16(.
190c0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 const void *file
190d0 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 name, /* Datab
190e0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 ase filename (UT
190f0 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 F-16) */. sqlit
19100 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 e3 **ppDb
19110 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 /* OUT: SQLit
19120 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 e db handle */.)
19130 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
19140 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
19150 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a (. const char *
19160 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 filename, /* D
19170 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 atabase filename
19180 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 (UTF-8) */. sq
19190 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 lite3 **ppDb,
191a0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 /* OUT: SQ
191b0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a Lite db handle *
191c0 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 /. int flags,
191d0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 /* F
191e0 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 lags */. const
191f0 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 char *zVfs
19200 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 /* Name of VFS
19210 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a module to use *
19220 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.);../*.** CAPI
19230 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 3REF: Error Code
19240 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 20 7b s And Messages {
19250 48 31 32 38 30 30 7d 20 3c 53 36 30 32 30 30 3e H12800} <S60200>
19260 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
19270 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 e3_errcode() int
19280 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 erface returns t
19290 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 he numeric [resu
192a0 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b lt code] or.** [
192b0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
192c0 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f code] for the mo
192d0 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 st recent failed
192e0 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 sqlite3_* API c
192f0 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 all.** associate
19300 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 d with a [databa
19310 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 se connection].
19320 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 If a prior API c
19330 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 all failed.** bu
19340 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e t the most recen
19350 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 t API call succe
19360 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e eded, the return
19370 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 value from.** s
19380 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 qlite3_errcode()
19390 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 is undefined.
193a0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 The sqlite3_exte
193b0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a nded_errcode().*
193c0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 * interface is t
193d0 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 he same except t
193e0 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 hat it always re
193f0 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 turns the .** [e
19400 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
19410 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 ode] even when e
19420 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
19430 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 odes are.** disa
19440 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 bled..**.** The
19450 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 sqlite3_errmsg()
19460 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 and sqlite3_err
19470 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 msg16() return E
19480 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a nglish-language.
19490 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 ** text that des
194a0 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 cribes the error
194b0 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d , as either UTF-
194c0 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 8 or UTF-16 resp
194d0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d ectively..** Mem
194e0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 ory to hold the
194f0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 error message st
19500 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 ring is managed
19510 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 internally..** T
19520 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 he application d
19530 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 oes not need to
19540 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 worry about free
19550 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a ing the result..
19560 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 ** However, the
19570 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 error string mig
19580 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 ht be overwritte
19590 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 n or deallocated
195a0 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e by.** subsequen
195b0 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 t calls to other
195c0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
195d0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a e functions..**.
195e0 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 ** When the seri
195f0 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e alized [threadin
19600 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 g mode] is in us
19610 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 e, it might be t
19620 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 he.** case that
19630 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f a second error o
19640 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 ccurs on a separ
19650 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 ate thread in be
19660 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d tween.** the tim
19670 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 e of the first e
19680 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c rror and the cal
19690 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 l to these inter
196a0 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 faces..** When t
196b0 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 hat happens, the
196c0 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 second error wi
196d0 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 ll be reported s
196e0 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e ince these.** in
196f0 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 terfaces always
19700 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 report the most
19710 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 recent result.
19720 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 To avoid.** this
19730 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 , each thread ca
19740 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 n obtain exclusi
19750 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 ve use of the [d
19760 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
19770 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f on] D.** by invo
19780 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 king [sqlite3_mu
19790 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 tex_enter]([sqli
197a0 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 te3_db_mutex](D)
197b0 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 ) before beginni
197c0 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 ng.** to use D a
197d0 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c nd invoking [sql
197e0 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 ite3_mutex_leave
197f0 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 ]([sqlite3_db_mu
19800 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a tex](D)) after.*
19810 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 * all calls to t
19820 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 he interfaces li
19830 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f sted here are co
19840 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 mpleted..**.** I
19850 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 f an interface f
19860 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 ails with SQLITE
19870 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 _MISUSE, that me
19880 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 ans the interfac
19890 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 e.** was invoked
198a0 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 incorrectly by
198b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e the application.
198c0 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 In that case,
198d0 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 the.** error cod
198e0 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 e and message ma
198f0 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 y or may not be
19900 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 set..**.** Requi
19910 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 rements:.** [H12
19920 38 30 31 5d 20 5b 48 31 32 38 30 32 5d 20 5b 48 801] [H12802] [H
19930 31 32 38 30 33 5d 20 5b 48 31 32 38 30 37 5d 20 12803] [H12807]
19940 5b 48 31 32 38 30 38 5d 20 5b 48 31 32 38 30 39 [H12808] [H12809
19950 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
19960 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 int sqlite3_errc
19970 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 ode(sqlite3 *db)
19980 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
19990 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 sqlite3_extende
199a0 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 d_errcode(sqlite
199b0 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 3 *db);.SQLITE_A
199c0 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 PI const char *s
199d0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 qlite3_errmsg(sq
199e0 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f lite3*);.SQLITE_
199f0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a API const void *
19a00 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 sqlite3_errmsg16
19a10 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
19a20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c ** CAPI3REF: SQL
19a30 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 Statement Objec
19a40 74 20 7b 48 31 33 30 30 30 7d 20 3c 48 31 33 30 t {H13000} <H130
19a50 31 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 10>.** KEYWORDS:
19a60 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 {prepared state
19a70 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 ment} {prepared
19a80 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a statements}.**.*
19a90 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 * An instance of
19aa0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 this object rep
19ab0 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 resents a single
19ac0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a SQL statement..
19ad0 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 ** This object i
19ae0 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 s variously know
19af0 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64 n as a "prepared
19b00 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 statement" or a
19b10 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 .** "compiled SQ
19b20 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 L statement" or
19b30 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 simply as a "sta
19b40 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 tement"..**.** T
19b50 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 he life of a sta
19b60 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f tement object go
19b70 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b es something lik
19b80 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f e this:.**.** <o
19b90 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 l>.** <li> Creat
19ba0 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 e the object usi
19bb0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ng [sqlite3_prep
19bc0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 are_v2()] or a r
19bd0 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 elated.** f
19be0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e unction..** <li>
19bf0 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 Bind values to
19c00 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 [host parameters
19c10 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 ] using the sqli
19c20 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 te3_bind_*().**
19c30 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e interfaces.
19c40 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 .** <li> Run the
19c50 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 SQL by calling
19c60 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
19c70 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d one or more tim
19c80 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 es..** <li> Rese
19c90 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 t the statement
19ca0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 using [sqlite3_r
19cb0 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 eset()] then go
19cc0 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 back.** to
19cd0 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 step 2. Do this
19ce0 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 zero or more ti
19cf0 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 mes..** <li> Des
19d00 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 troy the object
19d10 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 using [sqlite3_f
19d20 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c inalize()]..** <
19d30 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 /ol>.**.** Refer
19d40 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f to documentatio
19d50 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 n on individual
19d60 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f methods above fo
19d70 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 r additional.**
19d80 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a information..*/.
19d90 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
19da0 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 qlite3_stmt sqli
19db0 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a te3_stmt;../*.**
19dc0 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 CAPI3REF: Run-t
19dd0 69 6d 65 20 4c 69 6d 69 74 73 20 7b 48 31 32 37 ime Limits {H127
19de0 36 30 7d 20 3c 53 32 30 36 30 30 3e 0a 2a 2a 0a 60} <S20600>.**.
19df0 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 ** This interfac
19e00 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a e allows the siz
19e10 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e e of various con
19e20 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 structs to be li
19e30 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f mited.** on a co
19e40 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e nnection by conn
19e50 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 ection basis. T
19e60 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
19e70 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 er is the.** [da
19e80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
19e90 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 n] whose limit i
19ea0 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 s to be set or q
19eb0 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 ueried. The.**
19ec0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
19ed0 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b is one of the [
19ee0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 limit categories
19ef0 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a ] that define a.
19f00 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 ** class of cons
19f10 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a tructs to be siz
19f20 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 e limited. The
19f30 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
19f40 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 is the.** new li
19f50 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e mit for that con
19f60 73 74 72 75 63 74 2e 20 20 54 68 65 20 66 75 6e struct. The fun
19f70 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 ction returns th
19f80 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 0a 2a 2a 0a e old limit..**.
19f90 2a 2a 20 49 66 20 74 68 65 20 6e 65 77 20 6c 69 ** If the new li
19fa0 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 mit is a negativ
19fb0 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 e number, the li
19fc0 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 mit is unchanged
19fd0 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6c 69 6d ..** For the lim
19fe0 69 74 20 63 61 74 65 67 6f 72 79 20 6f 66 20 53 it category of S
19ff0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 59 5a 20 QLITE_LIMIT_XYZ
1a000 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b there is a .** [
1a010 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 limits | hard up
1a020 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 per bound].** se
1a030 74 20 62 79 20 61 20 63 6f 6d 70 69 6c 65 2d 74 t by a compile-t
1a040 69 6d 65 20 43 20 70 72 65 70 72 6f 63 65 73 73 ime C preprocess
1a050 6f 72 20 6d 61 63 72 6f 20 6e 61 6d 65 64 20 0a or macro named .
1a060 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c ** [limits | SQL
1a070 49 54 45 5f 4d 41 58 5f 58 59 5a 5d 2e 0a 2a 2a ITE_MAX_XYZ]..**
1a080 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 (The "_LIMIT_"
1a090 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 in the name is c
1a0a0 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f hanged to "_MAX_
1a0b0 22 2e 29 0a 2a 2a 20 41 74 74 65 6d 70 74 73 20 ".).** Attempts
1a0c0 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 to increase a li
1a0d0 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 mit above its ha
1a0e0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 rd upper bound a
1a0f0 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 re.** silently t
1a100 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 runcated to the
1a110 68 61 72 64 20 75 70 70 65 72 20 6c 69 6d 69 74 hard upper limit
1a120 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 20 74 69 6d 65 ..**.** Run time
1a130 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 limits are inte
1a140 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 nded for use in
1a150 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 applications tha
1a160 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 t manage.** both
1a170 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 their own inter
1a180 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 nal database and
1a190 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 also databases
1a1a0 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c that are control
1a1b0 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 led.** by untrus
1a1c0 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 ted external sou
1a1d0 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c rces. An exampl
1a1e0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 e application mi
1a1f0 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 ght be a.** web
1a200 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 browser that has
1a210 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 its own databas
1a220 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 es for storing h
1a230 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 istory and.** se
1a240 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73 parate databases
1a250 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a controlled by J
1a260 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 avaScript applic
1a270 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 ations downloade
1a280 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 d.** off the Int
1a290 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 ernet. The inte
1a2a0 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 rnal databases c
1a2b0 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a an be given the.
1a2c0 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c ** large, defaul
1a2d0 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 t limits. Datab
1a2e0 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 ases managed by
1a2f0 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 external sources
1a300 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e can.** be given
1a310 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 much smaller li
1a320 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f mits designed to
1a330 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 prevent a denia
1a340 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 l of service.**
1a350 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 attack. Develop
1a360 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 ers might also w
1a370 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b ant to use the [
1a380 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
1a390 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 orizer()].** int
1a3a0 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 erface to furthe
1a3b0 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 r control untrus
1a3c0 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 ted SQL. The si
1a3d0 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 ze of the databa
1a3e0 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 se.** created by
1a3f0 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 an untrusted sc
1a400 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 ript can be cont
1a410 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a ained using the.
1a420 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 ** [max_page_cou
1a430 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a nt] [PRAGMA]..**
1a440 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 .** New run-time
1a450 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 limit categorie
1a460 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 s may be added i
1a470 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
1a480 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 s..**.** Require
1a490 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 37 36 ments:.** [H1276
1a4a0 32 5d 20 5b 48 31 32 37 36 36 5d 20 5b 48 31 32 2] [H12766] [H12
1a4b0 37 36 39 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 769].*/.SQLITE_A
1a4c0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c PI int sqlite3_l
1a4d0 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 imit(sqlite3*, i
1a4e0 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 nt id, int newVa
1a4f0 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 l);../*.** CAPI3
1a500 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 REF: Run-Time Li
1a510 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 20 7b mit Categories {
1a520 48 31 32 37 39 30 7d 20 3c 48 31 32 37 36 30 3e H12790} <H12760>
1a530 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c .** KEYWORDS: {l
1a540 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b imit category} {
1a550 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 limit categories
1a560 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f }.**.** These co
1a570 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 nstants define v
1a580 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e arious performan
1a590 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 ce limits.** tha
1a5a0 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 t can be lowered
1a5b0 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 at run-time usi
1a5c0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 ng [sqlite3_limi
1a5d0 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e t()]..** The syn
1a5e0 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 opsis of the mea
1a5f0 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 nings of the var
1a600 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 ious limits is s
1a610 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 hown below..** A
1a620 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d dditional inform
1a630 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 ation is availab
1a640 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 le at [limits |
1a650 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 Limits in SQLite
1a660 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a ]..**.** <dl>.**
1a670 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 <dt>SQLITE_LIMI
1a680 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a T_LENGTH</dt>.**
1a690 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
1a6a0 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 size of any str
1a6b0 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 ing or BLOB or t
1a6c0 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a 2a able row.<dd>.**
1a6d0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c .** <dt>SQLITE_L
1a6e0 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c IMIT_SQL_LENGTH<
1a6f0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
1a700 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f maximum length o
1a710 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 f an SQL stateme
1a720 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c nt.</dd>.**.** <
1a730 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
1a740 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c COLUMN</dt>.** <
1a750 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e dd>The maximum n
1a760 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
1a770 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 in a table defi
1a780 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 nition or in the
1a790 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f .** result set o
1a7a0 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 f a [SELECT] or
1a7b0 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 the maximum numb
1a7c0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e er of columns in
1a7d0 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 an index.** or
1a7e0 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f in an ORDER BY o
1a7f0 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 r GROUP BY claus
1a800 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 e.</dd>.**.** <d
1a810 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 t>SQLITE_LIMIT_E
1a820 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a XPR_DEPTH</dt>.*
1a830 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
1a840 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 m depth of the p
1a850 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 arse tree on any
1a860 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 expression.</dd
1a870 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
1a880 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e TE_LIMIT_COMPOUN
1a890 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a D_SELECT</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 74 65 72 6d 73 number of terms
1a8c0 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 in a compound S
1a8d0 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e ELECT statement.
1a8e0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
1a8f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 SQLITE_LIMIT_VDB
1a900 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 E_OP</dt>.** <dd
1a910 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d >The maximum num
1a920 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 ber of instructi
1a930 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c ons in a virtual
1a940 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d machine program
1a950 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c .** used to impl
1a960 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 ement an SQL sta
1a970 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a tement.</dd>.**.
1a980 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ** <dt>SQLITE_LI
1a990 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 MIT_FUNCTION_ARG
1a9a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
1a9b0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
1a9c0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 of arguments on
1a9d0 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e a function.</dd>
1a9e0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
1a9f0 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 E_LIMIT_ATTACHED
1aa00 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
1aa10 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
1aa20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 of [ATTACH | att
1aa30 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d ached databases]
1aa40 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
1aa50 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 >SQLITE_LIMIT_LI
1aa60 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 KE_PATTERN_LENGT
1aa70 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 H</dt>.** <dd>Th
1aa80 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 e maximum length
1aa90 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 of the pattern
1aaa0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
1aab0 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c [LIKE] or.** [GL
1aac0 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f OB] operators.</
1aad0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
1aae0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 LITE_LIMIT_VARIA
1aaf0 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a BLE_NUMBER</dt>.
1ab00 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
1ab10 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 72 um number of var
1ab20 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 53 51 4c iables in an SQL
1ab30 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 statement that
1ab40 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 2e can.** be bound.
1ab50 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
1ab60 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 SQLITE_LIMIT_TRI
1ab70 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a GGER_DEPTH</dt>.
1ab80 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
1ab90 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 um depth of recu
1aba0 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 rsion for trigge
1abb0 72 73 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c rs.</dd>.** </dl
1abc0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c >.*/.#define SQL
1abd0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 ITE_LIMIT_LENGTH
1abe0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1abf0 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 0.#define SQ
1ac00 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c LITE_LIMIT_SQL_L
1ac10 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 ENGTH
1ac20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 1.#define S
1ac30 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 QLITE_LIMIT_COLU
1ac40 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 MN
1ac50 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 2.#define
1ac60 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 SQLITE_LIMIT_EXP
1ac70 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 R_DEPTH
1ac80 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 3.#define
1ac90 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f SQLITE_LIMIT_CO
1aca0 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 MPOUND_SELECT
1acb0 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 4.#defin
1acc0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 e SQLITE_LIMIT_V
1acd0 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 DBE_OP
1ace0 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 5.#defi
1acf0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
1ad00 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 FUNCTION_ARG
1ad10 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 6.#def
1ad20 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
1ad30 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 _ATTACHED
1ad40 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 7.#de
1ad50 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
1ad60 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c T_LIKE_PATTERN_L
1ad70 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 ENGTH 8.#d
1ad80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
1ad90 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 IT_VARIABLE_NUMB
1ada0 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 ER 9.#
1adb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
1adc0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 MIT_TRIGGER_DEPT
1add0 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a H 10.
1ade0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1adf0 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 Compiling An SQ
1ae00 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 L Statement {H13
1ae10 30 31 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 010} <S10000>.**
1ae20 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 KEYWORDS: {SQL
1ae30 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c statement compil
1ae40 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 er}.**.** To exe
1ae50 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 cute an SQL quer
1ae60 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 y, it must first
1ae70 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 be compiled int
1ae80 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a o a byte-code.**
1ae90 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f program using o
1aea0 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 ne of these rout
1aeb0 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ines..**.** The
1aec0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 first argument,
1aed0 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 "db", is a [data
1aee0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
1aef0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 obtained from a
1af00 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 .** prior succes
1af10 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 sful call to [sq
1af20 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b lite3_open()], [
1af30 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
1af40 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 )] or.** [sqlite
1af50 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 3_open16()]. Th
1af60 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
1af70 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 ction must not h
1af80 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e ave been closed.
1af90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e .**.** The secon
1afa0 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 d argument, "zSq
1afb0 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 l", is the state
1afc0 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 ment to be compi
1afd0 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 led, encoded.**
1afe0 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 as either UTF-8
1aff0 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 or UTF-16. The
1b000 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
1b010 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 ) and sqlite3_pr
1b020 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e epare_v2().** in
1b030 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 terfaces use UTF
1b040 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f -8, and sqlite3_
1b050 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 prepare16() and
1b060 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
1b070 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 6_v2().** use UT
1b080 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 F-16..**.** If t
1b090 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e he nByte argumen
1b0a0 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a t is less than z
1b0b0 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 ero, then zSql i
1b0c0 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 s read up to the
1b0d0 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 .** first zero t
1b0e0 65 72 6d 69 6e 61 74 6f 72 2e 20 49 66 20 6e 42 erminator. If nB
1b0f0 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 yte is non-negat
1b100 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 ive, then it is
1b110 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e the maximum.** n
1b120 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 umber of bytes
1b130 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 read from zSql.
1b140 20 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e When nByte is n
1b150 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 on-negative, the
1b160 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 .** zSql string
1b170 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74 ends at either t
1b180 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 he first '\000'
1b190 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 or '\u0000' char
1b1a0 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 acter or.** the
1b1b0 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 nByte-th byte, w
1b1c0 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 hichever comes f
1b1d0 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c irst. If the cal
1b1e0 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 ler knows.** tha
1b1f0 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 t the supplied s
1b200 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 tring is nul-ter
1b210 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 minated, then th
1b220 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a ere is a small.*
1b230 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 * performance ad
1b240 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 vantage to be ga
1b250 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 ined by passing
1b260 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 an nByte paramet
1b270 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 er that.** is eq
1b280 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 ual to the numbe
1b290 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
1b2a0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c e input string <
1b2b0 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a i>including</i>.
1b2c0 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 ** the nul-termi
1b2d0 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a nator bytes..**.
1b2e0 2a 2a 20 49 66 20 70 7a 54 61 69 6c 20 69 73 20 ** If pzTail is
1b2f0 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 not NULL then *p
1b300 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f zTail is made to
1b310 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 point to the fi
1b320 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 rst byte.** past
1b330 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 the end of the
1b340 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d first SQL statem
1b350 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 ent in zSql. Th
1b360 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c ese routines onl
1b370 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 y.** compile the
1b380 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 first statement
1b390 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a in zSql, so *pz
1b3a0 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 Tail is left poi
1b3b0 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 nting to.** what
1b3c0 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 remains uncompi
1b3d0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 led..**.** *ppSt
1b3e0 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 mt is left point
1b3f0 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 ing to a compile
1b400 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 d [prepared stat
1b410 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 ement] that can
1b420 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 be.** executed u
1b430 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 sing [sqlite3_st
1b440 65 70 28 29 5d 2e 20 20 49 66 20 74 68 65 72 65 ep()]. If there
1b450 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 is an error, *p
1b460 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 pStmt is set.**
1b470 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 to NULL. If the
1b480 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 input text cont
1b490 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 ains no SQL (if
1b4a0 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 the input is an
1b4b0 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 empty.** string
1b4c0 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 or a comment) th
1b4d0 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 en *ppStmt is se
1b4e0 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 t to NULL..** Th
1b4f0 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 e calling proced
1b500 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 ure is responsib
1b510 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 le for deleting
1b520 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 the compiled.**
1b530 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 SQL statement us
1b540 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e ing [sqlite3_fin
1b550 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 alize()] after i
1b560 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 t has finished w
1b570 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d ith it..** ppStm
1b580 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c t may not be NUL
1b590 4c 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 L..**.** On succ
1b5a0 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d ess, [SQLITE_OK]
1b5b0 20 69 73 20 72 65 74 75 72 6e 65 64 2c 20 6f 74 is returned, ot
1b5c0 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f herwise an [erro
1b5d0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 r code] is retur
1b5e0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ned..**.** The s
1b5f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1b600 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 2() and sqlite3_
1b610 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 prepare16_v2() i
1b620 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a nterfaces are.**
1b630 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 recommended for
1b640 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d all new program
1b650 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 s. The two older
1b660 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
1b670 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 retained.** for
1b680 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 backwards compat
1b690 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 ibility, but the
1b6a0 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 ir use is discou
1b6b0 72 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 raged..** In the
1b6c0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 "v2" interfaces
1b6d0 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 , the prepared s
1b6e0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 tatement.** that
1b6f0 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 is returned (th
1b700 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d e [sqlite3_stmt]
1b710 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e object) contain
1b720 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a s a copy of the.
1b730 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 ** original SQL
1b740 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 text. This cause
1b750 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 s the [sqlite3_s
1b760 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 tep()] interface
1b770 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61 20 to.** behave a
1b780 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 differently in t
1b790 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c wo ways:.**.** <
1b7a0 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 ol>.** <li>.** I
1b7b0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 f the database s
1b7c0 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 chema changes, i
1b7d0 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e nstead of return
1b7e0 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 ing [SQLITE_SCHE
1b7f0 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 MA] as it.** alw
1b800 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 ays used to do,
1b810 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
1b820 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 will automatica
1b830 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 lly recompile th
1b840 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 e SQL.** stateme
1b850 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 nt and try to ru
1b860 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 49 66 20 n it again. If
1b870 74 68 65 20 73 63 68 65 6d 61 20 68 61 73 20 63 the schema has c
1b880 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 hanged in.** a w
1b890 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 ay that makes th
1b8a0 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c e statement no l
1b8b0 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 onger valid, [sq
1b8c0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 lite3_step()] wi
1b8d0 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 ll still.** retu
1b8e0 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d rn [SQLITE_SCHEM
1b8f0 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 A]. But unlike
1b900 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 the legacy behav
1b910 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 ior, [SQLITE_SCH
1b920 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 EMA] is.** now a
1b930 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 fatal error. C
1b940 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
1b950 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67 prepare_v2()] ag
1b960 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b ain will not mak
1b970 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 e the.** error g
1b980 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 o away. Note: u
1b990 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d se [sqlite3_errm
1b9a0 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 sg()] to find th
1b9b0 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 e text.** of the
1b9c0 20 70 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74 parsing error t
1b9d0 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61 hat results in a
1b9e0 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 n [SQLITE_SCHEMA
1b9f0 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c ] return..** </l
1ba00 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a i>.**.** <li>.**
1ba10 20 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f When an error o
1ba20 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f ccurs, [sqlite3_
1ba30 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 step()] will ret
1ba40 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 urn one of the d
1ba50 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f etailed.** [erro
1ba60 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 r codes] or [ext
1ba70 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 ended error code
1ba80 73 5d 2e 20 20 54 68 65 20 6c 65 67 61 63 79 20 s]. The legacy
1ba90 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 behavior was tha
1baa0 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 t.** [sqlite3_st
1bab0 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 ep()] would only
1bac0 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 return a generi
1bad0 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d c [SQLITE_ERROR]
1bae0 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 result code.**
1baf0 61 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 and you would ha
1bb00 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 ve to make a sec
1bb10 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ond call to [sql
1bb20 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 69 6e ite3_reset()] in
1bb30 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 66 69 6e order.** to fin
1bb40 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 d the underlying
1bb50 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 cause of the pr
1bb60 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 oblem. With the
1bb70 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 "v2" prepare.**
1bb80 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 interfaces, the
1bb90 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f underlying reaso
1bba0 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 n for the error
1bbb0 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 is returned imme
1bbc0 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 diately..** </li
1bbd0 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a >.** </ol>.**.**
1bbe0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
1bbf0 2a 20 5b 48 31 33 30 31 31 5d 20 5b 48 31 33 30 * [H13011] [H130
1bc00 31 32 5d 20 5b 48 31 33 30 31 33 5d 20 5b 48 31 12] [H13013] [H1
1bc10 33 30 31 34 5d 20 5b 48 31 33 30 31 35 5d 20 5b 3014] [H13015] [
1bc20 48 31 33 30 31 36 5d 20 5b 48 31 33 30 31 39 5d H13016] [H13019]
1bc30 20 5b 48 31 33 30 32 31 5d 0a 2a 2a 0a 2a 2f 0a [H13021].**.*/.
1bc40 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
1bc50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a qlite3_prepare(.
1bc60 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
1bc70 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 /* Dat
1bc80 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a abase handle */.
1bc90 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 const char *zS
1bca0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c ql, /* SQL
1bcb0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d statement, UTF-
1bcc0 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 8 encoded */. i
1bcd0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 nt nByte,
1bce0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 /* Maximu
1bcf0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c m length of zSql
1bd00 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 in bytes. */.
1bd10 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 sqlite3_stmt **p
1bd20 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 pStmt, /* OUT:
1bd30 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 Statement handle
1bd40 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
1bd50 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a **pzTail /*
1bd60 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f OUT: Pointer to
1bd70 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 unused portion
1bd80 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 of zSql */.);.SQ
1bd90 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
1bda0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
1bdb0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
1bdc0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 /* Da
1bdd0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f tabase handle */
1bde0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
1bdf0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 Sql, /* SQ
1be00 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 L statement, UTF
1be10 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 -8 encoded */.
1be20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 int nByte,
1be30 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d /* Maxim
1be40 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 um length of zSq
1be50 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 l in bytes. */.
1be60 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a sqlite3_stmt **
1be70 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a ppStmt, /* OUT:
1be80 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c Statement handl
1be90 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
1bea0 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f r **pzTail /
1beb0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 * OUT: Pointer t
1bec0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e o unused portion
1bed0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 of zSql */.);.S
1bee0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
1bef0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
1bf00 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
1bf10 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 /* Da
1bf20 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f tabase handle */
1bf30 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a . const void *z
1bf40 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 Sql, /* SQ
1bf50 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 L statement, UTF
1bf60 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 -16 encoded */.
1bf70 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 int nByte,
1bf80 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 /* Maxi
1bf90 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 mum length of zS
1bfa0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a ql in bytes. */.
1bfb0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a sqlite3_stmt *
1bfc0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 *ppStmt, /* OUT
1bfd0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 : Statement hand
1bfe0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f le */. const vo
1bff0 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 id **pzTail
1c000 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 /* OUT: Pointer
1c010 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f to unused portio
1c020 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a n of zSql */.);.
1c030 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
1c040 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
1c050 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a _v2(. sqlite3 *
1c060 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f db, /
1c070 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c * Database handl
1c080 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 e */. const voi
1c090 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f d *zSql, /
1c0a0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c * SQL statement,
1c0b0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 UTF-16 encoded
1c0c0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 */. int nByte,
1c0d0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
1c0e0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f Maximum length o
1c0f0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e f zSql in bytes.
1c100 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 */. sqlite3_st
1c110 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a mt **ppStmt, /*
1c120 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 OUT: Statement
1c130 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
1c140 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 t void **pzTail
1c150 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e /* OUT: Poin
1c160 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f ter to unused po
1c170 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f rtion of zSql */
1c180 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
1c190 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 REF: Retrieving
1c1a0 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 20 7b 48 Statement SQL {H
1c1b0 31 33 31 30 30 7d 20 3c 48 31 33 30 30 30 3e 0a 13100} <H13000>.
1c1c0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 **.** This inter
1c1d0 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 face can be used
1c1e0 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 to retrieve a s
1c1f0 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 aved copy of the
1c200 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c original.** SQL
1c210 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 text used to cr
1c220 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 eate a [prepared
1c230 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 statement] if t
1c240 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 hat statement wa
1c250 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 s.** compiled us
1c260 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 ing either [sqli
1c270 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
1c280 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 ] or [sqlite3_pr
1c290 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a epare16_v2()]..*
1c2a0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
1c2b0 73 3a 0a 2a 2a 20 5b 48 31 33 31 30 31 5d 20 5b s:.** [H13101] [
1c2c0 48 31 33 31 30 32 5d 20 5b 48 31 33 31 30 33 5d H13102] [H13103]
1c2d0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 .*/.SQLITE_API c
1c2e0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
1c2f0 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 e3_sql(sqlite3_s
1c300 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a tmt *pStmt);../*
1c310 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 .** CAPI3REF: Dy
1c320 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 namically Typed
1c330 56 61 6c 75 65 20 4f 62 6a 65 63 74 20 7b 48 31 Value Object {H1
1c340 35 30 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 5000} <S20200>.*
1c350 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f * KEYWORDS: {pro
1c360 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
1c370 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 alue} {unprotect
1c380 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
1c390 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 }.**.** SQLite u
1c3a0 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f ses the sqlite3_
1c3b0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 value object to
1c3c0 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 represent all va
1c3d0 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e lues.** that can
1c3e0 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 be stored in a
1c3f0 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 database table.
1c400 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 SQLite uses dyna
1c410 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f mic typing.** fo
1c420 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 r the values it
1c430 73 74 6f 72 65 73 2e 20 56 61 6c 75 65 73 20 73 stores. Values s
1c440 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 tored in sqlite3
1c450 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a _value objects.*
1c460 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 * can be integer
1c470 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e s, floating poin
1c480 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 t values, string
1c490 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c s, BLOBs, or NUL
1c4a0 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 L..**.** An sqli
1c4b0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
1c4c0 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 may be either "
1c4d0 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 protected" or "u
1c4e0 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 nprotected"..**
1c4f0 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 Some interfaces
1c500 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 require a protec
1c510 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
1c520 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 e. Other interf
1c530 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 aces.** will acc
1c540 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f ept either a pro
1c550 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 tected or an unp
1c560 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
1c570 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 _value..** Every
1c580 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 interface that
1c590 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f accepts sqlite3_
1c5a0 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 value arguments
1c5b0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 specifies.** whe
1c5c0 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 ther or not it r
1c5d0 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 equires a protec
1c5e0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
1c5f0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 e..**.** The ter
1c600 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 ms "protected" a
1c610 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 nd "unprotected"
1c620 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 refer to whethe
1c630 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 r or not.** a mu
1c640 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 20 tex is held. A
1c650 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 internal mutex i
1c660 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f s held for a pro
1c670 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 tected.** sqlite
1c680 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 3_value object b
1c690 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 ut no mutex is h
1c6a0 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f eld for an unpro
1c6b0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 tected.** sqlite
1c6c0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 3_value object.
1c6d0 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f If SQLite is co
1c6e0 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e mpiled to be sin
1c6f0 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 gle-threaded.**
1c700 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 (with [SQLITE_TH
1c710 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 READSAFE=0] and
1c720 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 with [sqlite3_th
1c730 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 readsafe()] retu
1c740 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 rning 0).** or i
1c750 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 f SQLite is run
1c760 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 in one of reduce
1c770 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a d mutex modes .*
1c780 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 * [SQLITE_CONFIG
1c790 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f _SINGLETHREAD] o
1c7a0 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 r [SQLITE_CONFIG
1c7b0 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a _MULTITHREAD].**
1c7c0 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e then there is n
1c7d0 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 o distinction be
1c7e0 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 tween protected
1c7f0 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a and unprotected.
1c800 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ** sqlite3_value
1c810 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 objects and the
1c820 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e y can be used in
1c830 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 terchangeably.
1c840 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 However,.** for
1c850 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 maximum code por
1c860 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 tability it is r
1c870 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 ecommended that
1c880 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 applications.**
1c890 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 still make the d
1c8a0 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 istinction betwe
1c8b0 65 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 en between prote
1c8c0 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 cted and unprote
1c8d0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f cted.** sqlite3_
1c8e0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 value objects ev
1c8f0 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 en when not stri
1c900 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a ctly required..*
1c910 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
1c920 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 _value objects t
1c930 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61 hat are passed a
1c940 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 s parameters int
1c950 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 o the.** impleme
1c960 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c ntation of [appl
1c970 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
1c980 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 SQL functions] a
1c990 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a re protected..**
1c9a0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c The sqlite3_val
1c9b0 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e ue object return
1c9c0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 ed by.** [sqlite
1c9d0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 3_column_value()
1c9e0 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 ] is unprotected
1c9f0 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 ..** Unprotected
1ca00 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
1ca10 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 bjects may only
1ca20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 be used with.**
1ca30 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
1ca40 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 value()] and [sq
1ca50 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 lite3_bind_value
1ca60 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c ()]..** The [sql
1ca70 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 ite3_value_blob
1ca80 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f | sqlite3_value_
1ca90 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f type()] family o
1caa0 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 f.** interfaces
1cab0 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 require protecte
1cac0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 d sqlite3_value
1cad0 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 objects..*/.type
1cae0 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 def struct Mem s
1caf0 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f qlite3_value;../
1cb00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
1cb10 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 QL Function Cont
1cb20 65 78 74 20 4f 62 6a 65 63 74 20 7b 48 31 36 30 ext Object {H160
1cb30 30 31 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 01} <S20200>.**.
1cb40 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 ** The context i
1cb50 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 n which an SQL f
1cb60 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 unction executes
1cb70 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e is stored in an
1cb80 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 .** sqlite3_cont
1cb90 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 41 20 70 ext object. A p
1cba0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c ointer to an sql
1cbb0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a ite3_context obj
1cbc0 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 ect.** is always
1cbd0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
1cbe0 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e to [application
1cbf0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
1cc00 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 ctions]..** The
1cc10 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
1cc20 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ned SQL function
1cc30 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
1cc40 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a will pass this.*
1cc50 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 * pointer throug
1cc60 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 h into calls to
1cc70 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
1cc80 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 int | sqlite3_re
1cc90 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c sult()],.** [sql
1cca0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
1ccb0 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 ontext()], [sqli
1ccc0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d te3_user_data()]
1ccd0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f ,.** [sqlite3_co
1cce0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 ntext_db_handle(
1ccf0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 )], [sqlite3_get
1cd00 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 _auxdata()],.**
1cd10 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f and/or [sqlite3_
1cd20 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a set_auxdata()]..
1cd30 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
1cd40 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 t sqlite3_contex
1cd50 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 t sqlite3_contex
1cd60 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 t;../*.** CAPI3R
1cd70 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 EF: Binding Valu
1cd80 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 es To Prepared S
1cd90 74 61 74 65 6d 65 6e 74 73 20 7b 48 31 33 35 30 tatements {H1350
1cda0 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 20 4b 0} <S70300>.** K
1cdb0 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 EYWORDS: {host p
1cdc0 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 arameter} {host
1cdd0 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 parameters} {hos
1cde0 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 t parameter name
1cdf0 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b }.** KEYWORDS: {
1ce00 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b SQL parameter} {
1ce10 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 SQL parameters}
1ce20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 {parameter bindi
1ce30 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 ng}.**.** In the
1ce40 20 53 51 4c 20 73 74 72 69 6e 67 73 20 69 6e 70 SQL strings inp
1ce50 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 ut to [sqlite3_p
1ce60 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 repare_v2()] and
1ce70 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a its variants,.*
1ce80 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 * literals may b
1ce90 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 e replaced by a
1cea0 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 [parameter] that
1ceb0 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 matches one of
1cec0 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d following.** tem
1ced0 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 plates:.**.** <u
1cee0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a l>.** <li> ?.**
1cef0 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c <li> ?NNN.** <
1cf00 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 li> :VVV.** <li
1cf10 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 > @VVV.** <li>
1cf20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a $VVV.** </ul>.*
1cf30 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 *.** In the temp
1cf40 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e lates above, NNN
1cf50 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 represents an i
1cf60 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a nteger literal,.
1cf70 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 ** and VVV repre
1cf80 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 sents an alphanu
1cf90 6d 65 72 69 63 20 69 64 65 6e 74 69 66 65 72 2e meric identifer.
1cfa0 20 20 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 The values of
1cfb0 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 these.** paramet
1cfc0 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 ers (also called
1cfd0 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 "host parameter
1cfe0 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 names" or "SQL
1cff0 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 parameters").**
1d000 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 can be set using
1d010 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e the sqlite3_bin
1d020 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 d_*() routines d
1d030 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a efined here..**.
1d040 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 ** The first arg
1d050 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c ument to the sql
1d060 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f ite3_bind_*() ro
1d070 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 utines is always
1d080 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f .** a pointer to
1d090 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 the [sqlite3_st
1d0a0 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 mt] object retur
1d0b0 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c ned from.** [sql
1d0c0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
1d0d0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e )] or its varian
1d0e0 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 ts..**.** The se
1d0f0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 cond argument is
1d100 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 the index of th
1d110 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 e SQL parameter
1d120 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 54 68 to be set..** Th
1d130 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 e leftmost SQL p
1d140 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 arameter has an
1d150 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 57 68 65 index of 1. Whe
1d160 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 n the same named
1d170 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 .** SQL paramete
1d180 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 r is used more t
1d190 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 han once, second
1d1a0 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a and subsequent.
1d1b0 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 ** occurrences h
1d1c0 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 ave the same ind
1d1d0 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 ex as the first
1d1e0 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 54 occurrence..** T
1d1f0 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d he index for nam
1d200 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 ed parameters ca
1d210 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 n be looked up u
1d220 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c sing the.** [sql
1d230 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
1d240 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 ter_index()] API
1d250 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 54 68 if desired. Th
1d260 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 e index.** for "
1d270 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 ?NNN" parameters
1d280 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 is the value of
1d290 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e NNN..** The NNN
1d2a0 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 value must be b
1d2b0 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 etween 1 and the
1d2c0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 [sqlite3_limit(
1d2d0 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 )].** parameter
1d2e0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 [SQLITE_LIMIT_VA
1d2f0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 RIABLE_NUMBER] (
1d300 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 default value: 9
1d310 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 99)..**.** The t
1d320 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 hird argument is
1d330 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 the value to bi
1d340 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 nd to the parame
1d350 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 ter..**.** In th
1d360 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 ose routines tha
1d370 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 t have a fourth
1d380 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 argument, its va
1d390 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 lue is the.** nu
1d3a0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e mber of bytes in
1d3b0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 the parameter.
1d3c0 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 To be clear: th
1d3d0 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a e value is the.*
1d3e0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 * number of <u>b
1d3f0 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 ytes</u> in the
1d400 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e value, not the n
1d410 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 umber of charact
1d420 65 72 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 ers..** If the f
1d430 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
1d440 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 is negative, the
1d450 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 length of the s
1d460 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 tring is.** the
1d470 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
1d480 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 up to the first
1d490 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e zero terminator.
1d4a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 .**.** The fifth
1d4b0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c argument to sql
1d4c0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 ite3_bind_blob()
1d4d0 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 , sqlite3_bind_t
1d4e0 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 ext(), and.** sq
1d4f0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 lite3_bind_text1
1d500 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63 6() is a destruc
1d510 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 tor used to disp
1d520 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 ose of the BLOB
1d530 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 or.** string aft
1d540 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 er SQLite has fi
1d550 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 nished with it.
1d560 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 If the fifth arg
1d570 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 ument is.** the
1d580 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 special value [S
1d590 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 QLITE_STATIC], t
1d5a0 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d hen SQLite assum
1d5b0 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 es that the.** i
1d5c0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e nformation is in
1d5d0 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 static, unmanag
1d5e0 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 ed space and doe
1d5f0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 s not need to be
1d600 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 74 68 freed..** If th
1d610 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 e fifth argument
1d620 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b has the value [
1d630 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 SQLITE_TRANSIENT
1d640 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 ], then.** SQLit
1d650 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 e makes its own
1d660 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 private copy of
1d670 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 the data immedia
1d680 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 tely, before.**
1d690 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 the sqlite3_bind
1d6a0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 _*() routine ret
1d6b0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 urns..**.** The
1d6c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 sqlite3_bind_zer
1d6d0 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 oblob() routine
1d6e0 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 binds a BLOB of
1d6f0 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a length N that.**
1d700 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 is filled with
1d710 7a 65 72 6f 65 73 2e 20 20 41 20 7a 65 72 6f 62 zeroes. A zerob
1d720 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 lob uses a fixed
1d730 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 amount of memor
1d740 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e y.** (just an in
1d750 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 teger to hold it
1d760 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 s size) while it
1d770 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 is being proces
1d780 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 sed..** Zeroblob
1d790 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 s are intended t
1d7a0 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 o serve as place
1d7b0 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 holders for BLOB
1d7c0 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 s whose.** conte
1d7d0 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 nt is later writ
1d7e0 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 ten using.** [sq
1d7f0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 lite3_blob_open
1d800 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c | incremental BL
1d810 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 OB I/O] routines
1d820 2e 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20 ..** A negative
1d830 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 value for the ze
1d840 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 roblob results i
1d850 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 n a zero-length
1d860 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 BLOB..**.** The
1d870 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 sqlite3_bind_*()
1d880 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 routines must b
1d890 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a e called after.*
1d8a0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
1d8b0 72 65 5f 76 32 28 29 5d 20 28 61 6e 64 20 69 74 re_v2()] (and it
1d8c0 73 20 76 61 72 69 61 6e 74 73 29 20 6f 72 20 5b s variants) or [
1d8d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
1d8e0 20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b and.** before [
1d8f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e sqlite3_step()].
1d900 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20 61 72 65 .** Bindings are
1d910 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 not cleared by
1d920 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 the [sqlite3_res
1d930 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a et()] routine..*
1d940 2a 20 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 * Unbound parame
1d950 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 ters are interpr
1d960 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a eted as NULL..**
1d970 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
1d980 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 es return [SQLIT
1d990 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 E_OK] on success
1d9a0 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 or an error cod
1d9b0 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 e if.** anything
1d9c0 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53 goes wrong. [S
1d9d0 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 QLITE_RANGE] is
1d9e0 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 returned if the
1d9f0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 parameter.** ind
1da00 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e ex is out of ran
1da10 67 65 2e 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d ge. [SQLITE_NOM
1da20 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 EM] is returned
1da30 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c if malloc() fail
1da40 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 s..** [SQLITE_MI
1da50 53 55 53 45 5d 20 6d 69 67 68 74 20 62 65 20 72 SUSE] might be r
1da60 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 73 65 eturned if these
1da70 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 routines are ca
1da80 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 72 lled on a.** vir
1da90 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 74 68 61 tual machine tha
1daa0 74 20 69 73 20 74 68 65 20 77 72 6f 6e 67 20 73 t is the wrong s
1dab0 74 61 74 65 20 6f 72 20 77 68 69 63 68 20 68 61 tate or which ha
1dac0 73 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 66 s already been f
1dad0 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65 74 inalized..** Det
1dae0 65 63 74 69 6f 6e 20 6f 66 20 6d 69 73 75 73 65 ection of misuse
1daf0 20 69 73 20 75 6e 72 65 6c 69 61 62 6c 65 2e 20 is unreliable.
1db00 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 Applications sh
1db10 6f 75 6c 64 20 6e 6f 74 20 64 65 70 65 6e 64 0a ould not depend.
1db20 2a 2a 20 6f 6e 20 53 51 4c 49 54 45 5f 4d 49 53 ** on SQLITE_MIS
1db30 55 53 45 20 72 65 74 75 72 6e 73 2e 20 20 53 51 USE returns. SQ
1db40 4c 49 54 45 5f 4d 49 53 55 53 45 20 69 73 20 69 LITE_MISUSE is i
1db50 6e 74 65 6e 64 65 64 20 74 6f 20 69 6e 64 69 63 ntended to indic
1db60 61 74 65 20 61 0a 2a 2a 20 61 20 6c 6f 67 69 63 ate a.** a logic
1db70 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20 61 70 error in the ap
1db80 70 6c 69 63 61 74 69 6f 6e 2e 20 20 46 75 74 75 plication. Futu
1db90 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 re versions of S
1dba0 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 70 QLite might.** p
1dbb0 61 6e 69 63 20 72 61 74 68 65 72 20 74 68 61 6e anic rather than
1dbc0 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d return SQLITE_M
1dbd0 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 ISUSE..**.** See
1dbe0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
1dbf0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 bind_parameter_c
1dc00 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c ount()],.** [sql
1dc10 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
1dc20 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 ter_name()], and
1dc30 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
1dc40 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 arameter_index()
1dc50 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 ]..**.** Require
1dc60 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 35 30 ments:.** [H1350
1dc70 36 5d 20 5b 48 31 33 35 30 39 5d 20 5b 48 31 33 6] [H13509] [H13
1dc80 35 31 32 5d 20 5b 48 31 33 35 31 35 5d 20 5b 48 512] [H13515] [H
1dc90 31 33 35 31 38 5d 20 5b 48 31 33 35 32 31 5d 20 13518] [H13521]
1dca0 5b 48 31 33 35 32 34 5d 20 5b 48 31 33 35 32 37 [H13524] [H13527
1dcb0 5d 0a 2a 2a 20 5b 48 31 33 35 33 30 5d 20 5b 48 ].** [H13530] [H
1dcc0 31 33 35 33 33 5d 20 5b 48 31 33 35 33 36 5d 20 13533] [H13536]
1dcd0 5b 48 31 33 35 33 39 5d 20 5b 48 31 33 35 34 32 [H13539] [H13542
1dce0 5d 20 5b 48 31 33 35 34 35 5d 20 5b 48 31 33 35 ] [H13545] [H135
1dcf0 34 38 5d 20 5b 48 31 33 35 35 31 5d 0a 2a 2a 0a 48] [H13551].**.
1dd00 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
1dd10 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 t sqlite3_bind_b
1dd20 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 lob(sqlite3_stmt
1dd30 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f *, int, const vo
1dd40 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 id*, int n, void
1dd50 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c (*)(void*));.SQL
1dd60 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
1dd70 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 te3_bind_double(
1dd80 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
1dd90 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c nt, double);.SQL
1dda0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
1ddb0 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c te3_bind_int(sql
1ddc0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
1ddd0 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 int);.SQLITE_AP
1dde0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 I int sqlite3_bi
1ddf0 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 nd_int64(sqlite3
1de00 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c _stmt*, int, sql
1de10 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c ite3_int64);.SQL
1de20 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
1de30 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 te3_bind_null(sq
1de40 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
1de50 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
1de60 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 t sqlite3_bind_t
1de70 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ext(sqlite3_stmt
1de80 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 *, int, const ch
1de90 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 ar*, int n, void
1dea0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c (*)(void*));.SQL
1deb0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
1dec0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 te3_bind_text16(
1ded0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
1dee0 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c nt, const void*,
1def0 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f int, void(*)(vo
1df00 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 id*));.SQLITE_AP
1df10 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 I int sqlite3_bi
1df20 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 nd_value(sqlite3
1df30 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e _stmt*, int, con
1df40 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 st sqlite3_value
1df50 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 *);.SQLITE_API i
1df60 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
1df70 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 zeroblob(sqlite3
1df80 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 _stmt*, int, int
1df90 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 n);../*.** CAPI
1dfa0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 3REF: Number Of
1dfb0 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 20 7b SQL Parameters {
1dfc0 48 31 33 36 30 30 7d 20 3c 53 37 30 33 30 30 3e H13600} <S70300>
1dfd0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
1dfe0 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ine can be used
1dff0 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 to find the numb
1e000 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d er of [SQL param
1e010 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b eters].** in a [
1e020 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1e030 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 nt]. SQL parame
1e040 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 ters are tokens
1e050 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 of the.** form "
1e060 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 ?", "?NNN", ":AA
1e070 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 A", "$AAA", or "
1e080 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 @AAA" that serve
1e090 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 as.** placehold
1e0a0 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 ers for values t
1e0b0 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 hat are [sqlite3
1e0c0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 _bind_blob | bou
1e0d0 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 nd].** to the pa
1e0e0 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 rameters at a la
1e0f0 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 ter time..**.**
1e100 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 This routine act
1e110 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 ually returns th
1e120 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c e index of the l
1e130 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 argest (rightmos
1e140 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e t).** parameter.
1e150 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 For all forms e
1e160 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 xcept ?NNN, this
1e170 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 will correspond
1e180 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 to the.** numbe
1e190 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 r of unique para
1e1a0 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 meters. If para
1e1b0 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e meters of the ?N
1e1c0 4e 4e 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 NN are used,.**
1e1d0 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 there may be gap
1e1e0 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a s in the list..*
1e1f0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
1e200 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
1e210 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 b|sqlite3_bind()
1e220 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 ],.** [sqlite3_b
1e230 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 ind_parameter_na
1e240 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 me()], and.** [s
1e250 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
1e260 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a meter_index()]..
1e270 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
1e280 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 30 31 5d 0a ts:.** [H13601].
1e290 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
1e2a0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 t sqlite3_bind_p
1e2b0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 arameter_count(s
1e2c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a qlite3_stmt*);..
1e2d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1e2e0 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 Name Of A Host P
1e2f0 61 72 61 6d 65 74 65 72 20 7b 48 31 33 36 32 30 arameter {H13620
1e300 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a } <S70300>.**.**
1e310 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 This routine re
1e320 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
1e330 74 6f 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 to the name of t
1e340 68 65 20 6e 2d 74 68 0a 2a 2a 20 5b 53 51 4c 20 he n-th.** [SQL
1e350 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 20 parameter] in a
1e360 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
1e370 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20 70 61 72 ent]..** SQL par
1e380 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 ameters of the f
1e390 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a orm "?NNN" or ":
1e3a0 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f AAA" or "@AAA" o
1e3b0 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 r "$AAA".** have
1e3c0 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 a name which is
1e3d0 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e the string "?NN
1e3e0 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 N" or ":AAA" or
1e3f0 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 "@AAA" or "$AAA"
1e400 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 .** respectively
1e410 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f ..** In other wo
1e420 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c rds, the initial
1e430 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 ":" or "$" or "
1e440 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 @" or "?".** is
1e450 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 included as part
1e460 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a of the name..**
1e470 20 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 Parameters of t
1e480 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 he form "?" with
1e490 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 out a following
1e4a0 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 integer have no
1e4b0 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 name.** and are
1e4c0 61 6c 73 6f 20 72 65 66 65 72 72 65 64 20 74 6f also referred to
1e4d0 20 61 73 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 as "anonymous p
1e4e0 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a arameters"..**.*
1e4f0 2a 20 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 * The first host
1e500 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 parameter has a
1e510 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f n index of 1, no
1e520 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 t 0..**.** If th
1e530 65 20 76 61 6c 75 65 20 6e 20 69 73 20 6f 75 74 e value n is out
1e540 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 of range or if
1e550 74 68 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74 the n-th paramet
1e560 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 er is.** nameles
1e570 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 s, then NULL is
1e580 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 72 returned. The r
1e590 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 eturned string i
1e5a0 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 s.** always in U
1e5b0 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 TF-8 encoding ev
1e5c0 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 en if the named
1e5d0 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a parameter was.**
1e5e0 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 originally spec
1e5f0 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 ified as UTF-16
1e600 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 in [sqlite3_prep
1e610 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b are16()] or.** [
1e620 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
1e630 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 6_v2()]..**.** S
1e640 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
1e650 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 3_bind_blob|sqli
1e660 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 te3_bind()],.**
1e670 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
1e680 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d rameter_count()]
1e690 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 , and.** [sqlite
1e6a0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
1e6b0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a _index()]..**.**
1e6c0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
1e6d0 2a 20 5b 48 31 33 36 32 31 5d 0a 2a 2f 0a 53 51 * [H13621].*/.SQ
1e6e0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 LITE_API const c
1e6f0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e har *sqlite3_bin
1e700 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 d_parameter_name
1e710 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
1e720 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 int);../*.** CAP
1e730 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 I3REF: Index Of
1e740 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 A Parameter With
1e750 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 20 7b 48 A Given Name {H
1e760 31 33 36 34 30 7d 20 3c 53 37 30 33 30 30 3e 0a 13640} <S70300>.
1e770 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 **.** Return the
1e780 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c index of an SQL
1e790 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e parameter given
1e7a0 20 69 74 73 20 6e 61 6d 65 2e 20 20 54 68 65 0a its name. The.
1e7b0 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 ** index value r
1e7c0 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 eturned is suita
1e7d0 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 ble for use as t
1e7e0 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 he second.** par
1e7f0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 ameter to [sqlit
1e800 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c e3_bind_blob|sql
1e810 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 41 ite3_bind()]. A
1e820 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 zero.** is retu
1e830 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 rned if no match
1e840 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 ing parameter is
1e850 20 66 6f 75 6e 64 2e 20 20 54 68 65 20 70 61 72 found. The par
1e860 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d ameter.** name m
1e870 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 ust be given in
1e880 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 UTF-8 even if th
1e890 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 e original state
1e8a0 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 ment.** was prep
1e8b0 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 ared from UTF-16
1e8c0 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c text using [sql
1e8d0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
1e8e0 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 2()]..**.** See
1e8f0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 also: [sqlite3_b
1e900 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 ind_blob|sqlite3
1e910 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 _bind()],.** [sq
1e920 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
1e930 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 eter_count()], a
1e940 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 nd.** [sqlite3_b
1e950 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e ind_parameter_in
1e960 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 dex()]..**.** Re
1e970 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
1e980 48 31 33 36 34 31 5d 0a 2a 2f 0a 53 51 4c 49 54 H13641].*/.SQLIT
1e990 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
1e9a0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
1e9b0 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 _index(sqlite3_s
1e9c0 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 tmt*, const char
1e9d0 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a *zName);../*.**
1e9e0 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 CAPI3REF: Reset
1e9f0 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e All Bindings On
1ea00 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 A Prepared Stat
1ea10 65 6d 65 6e 74 20 7b 48 31 33 36 36 30 7d 20 3c ement {H13660} <
1ea20 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 43 6f S70300>.**.** Co
1ea30 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e ntrary to the in
1ea40 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c tuition of many,
1ea50 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
1ea60 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 )] does not rese
1ea70 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 t.** the [sqlite
1ea80 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 3_bind_blob | bi
1ea90 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 ndings] on a [pr
1eaa0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1eab0 5d 2e 0a 2a 2a 20 55 73 65 20 74 68 69 73 20 72 ]..** Use this r
1eac0 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 outine to reset
1ead0 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 all host paramet
1eae0 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a ers to NULL..**.
1eaf0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
1eb00 0a 2a 2a 20 5b 48 31 33 36 36 31 5d 0a 2a 2f 0a .** [H13661].*/.
1eb10 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
1eb20 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e qlite3_clear_bin
1eb30 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 dings(sqlite3_st
1eb40 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 mt*);../*.** CAP
1eb50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 I3REF: Number Of
1eb60 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 Columns In A Re
1eb70 73 75 6c 74 20 53 65 74 20 7b 48 31 33 37 31 30 sult Set {H13710
1eb80 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a } <S10700>.**.**
1eb90 20 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 Return the numb
1eba0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e er of columns in
1ebb0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 the result set
1ebc0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a returned by the.
1ebd0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ** [prepared sta
1ebe0 74 65 6d 65 6e 74 5d 2e 20 54 68 69 73 20 72 6f tement]. This ro
1ebf0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 utine returns 0
1ec00 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 if pStmt is an S
1ec10 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 QL.** statement
1ec20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 that does not re
1ec30 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 turn data (for e
1ec40 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 xample an [UPDAT
1ec50 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 E])..**.** Requi
1ec60 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 rements:.** [H13
1ec70 37 31 31 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 711].*/.SQLITE_A
1ec80 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 PI int sqlite3_c
1ec90 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 olumn_count(sqli
1eca0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
1ecb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1ecc0 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 F: Column Names
1ecd0 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 20 In A Result Set
1ece0 7b 48 31 33 37 32 30 7d 20 3c 53 31 30 37 30 30 {H13720} <S10700
1ecf0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f >.**.** These ro
1ed00 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 utines return th
1ed10 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 e name assigned
1ed20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 to a particular
1ed30 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 column.** in the
1ed40 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 result set of a
1ed50 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d [SELECT] statem
1ed60 65 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 ent. The sqlite
1ed70 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 3_column_name().
1ed80 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 ** interface ret
1ed90 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
1eda0 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 o a zero-termina
1edb0 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 ted UTF-8 string
1edc0 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f .** and sqlite3_
1edd0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 column_name16()
1ede0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
1edf0 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d r to a zero-term
1ee00 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 inated.** UTF-16
1ee10 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 66 69 string. The fi
1ee20 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 rst parameter is
1ee30 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
1ee40 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 tatement].** tha
1ee50 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 t implements the
1ee60 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d [SELECT] statem
1ee70 65 6e 74 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 ent. The second
1ee80 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
1ee90 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 .** column numbe
1eea0 72 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 r. The leftmost
1eeb0 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 column is numbe
1eec0 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 r 0..**.** The r
1eed0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 eturned string p
1eee0 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 ointer is valid
1eef0 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 until either the
1ef00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
1ef10 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 ment].** is dest
1ef20 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 royed by [sqlite
1ef30 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 3_finalize()] or
1ef40 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 until the next
1ef50 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 call to.** sqlit
1ef60 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 e3_column_name()
1ef70 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 or sqlite3_colu
1ef80 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 mn_name16() on t
1ef90 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a he same column..
1efa0 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 **.** If sqlite3
1efb0 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 _malloc() fails
1efc0 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 during the proce
1efd0 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 ssing of either
1efe0 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 routine.** (for
1eff0 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 example during a
1f000 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d conversion from
1f010 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 UTF-8 to UTF-16
1f020 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c ) then a.** NULL
1f030 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 pointer is retu
1f040 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 rned..**.** The
1f050 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 name of a result
1f060 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 column is the v
1f070 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 alue of the "AS"
1f080 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 clause for.** t
1f090 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 hat column, if t
1f0a0 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c here is an AS cl
1f0b0 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 ause. If there
1f0c0 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a is no AS clause.
1f0d0 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 ** then the name
1f0e0 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 of the column i
1f0f0 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e s unspecified an
1f100 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f d may change fro
1f110 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 m.** one release
1f120 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 of SQLite to th
1f130 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 e next..**.** Re
1f140 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
1f150 48 31 33 37 32 31 5d 20 5b 48 31 33 37 32 33 5d H13721] [H13723]
1f160 20 5b 48 31 33 37 32 34 5d 20 5b 48 31 33 37 32 [H13724] [H1372
1f170 35 5d 20 5b 48 31 33 37 32 36 5d 20 5b 48 31 33 5] [H13726] [H13
1f180 37 32 37 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 727].*/.SQLITE_A
1f190 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 PI const char *s
1f1a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
1f1b0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
1f1c0 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 , int N);.SQLITE
1f1d0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 _API const void
1f1e0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
1f1f0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 name16(sqlite3_s
1f200 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f tmt*, int N);../
1f210 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
1f220 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e ource Of Data In
1f230 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 A Query Result
1f240 7b 48 31 33 37 34 30 7d 20 3c 53 31 30 37 30 30 {H13740} <S10700
1f250 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f >.**.** These ro
1f260 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 utines provide a
1f270 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d means to determ
1f280 69 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e 20 ine what column
1f290 6f 66 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c 65 of what.** table
1f2a0 20 69 6e 20 77 68 69 63 68 20 64 61 74 61 62 61 in which databa
1f2b0 73 65 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 se a result of a
1f2c0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d [SELECT] statem
1f2d0 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a ent comes from..
1f2e0 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 ** The name of t
1f2f0 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 he database or t
1f300 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 able or column c
1f310 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 an be returned a
1f320 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 s.** either a UT
1f330 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 F-8 or UTF-16 st
1f340 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 61 74 61 ring. The _data
1f350 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 base_ routines r
1f360 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 eturn.** the dat
1f370 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 abase name, the
1f380 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 _table_ routines
1f390 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c return the tabl
1f3a0 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 e name, and.** t
1f3b0 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 he origin_ routi
1f3c0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 nes return the c
1f3d0 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 olumn name..** T
1f3e0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 he returned stri
1f3f0 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 ng is valid unti
1f400 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 l the [prepared
1f410 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 statement] is de
1f420 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 stroyed.** using
1f430 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
1f440 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 ze()] or until t
1f450 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 he same informat
1f460 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 ion is requested
1f470 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 .** again in a d
1f480 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e ifferent encodin
1f490 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d g..**.** The nam
1f4a0 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 es returned are
1f4b0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d the original un-
1f4c0 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 aliased names of
1f4d0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 the.** database
1f4e0 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c , table, and col
1f4f0 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 umn..**.** The f
1f500 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
1f510 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 the following c
1f520 61 6c 6c 73 20 69 73 20 61 20 5b 70 72 65 70 61 alls is a [prepa
1f530 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a red statement]..
1f540 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f ** These functio
1f550 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d ns return inform
1f560 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 ation about the
1f570 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 Nth column retur
1f580 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 ned by.** the st
1f590 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e atement, where N
1f5a0 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 is the second f
1f5b0 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 unction argument
1f5c0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e ..**.** If the N
1f5d0 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e th column return
1f5e0 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d ed by the statem
1f5f0 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 ent is an expres
1f600 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 sion or.** subqu
1f610 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 ery and is not a
1f620 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 column value, t
1f630 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 hen all of these
1f640 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 functions retur
1f650 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 54 68 65 73 n.** NULL. Thes
1f660 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 e routine might
1f670 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c also return NULL
1f680 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c if a memory all
1f690 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a ocation error.**
1f6a0 20 6f 63 63 75 72 73 2e 20 20 4f 74 68 65 72 77 occurs. Otherw
1f6b0 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e ise, they return
1f6c0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
1f6d0 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 attached databa
1f6e0 73 65 2c 20 74 61 62 6c 65 0a 2a 2a 20 61 6e 64 se, table.** and
1f6f0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 column that que
1f700 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e ry result column
1f710 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 was extracted f
1f720 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 rom..**.** As wi
1f730 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c th all other SQL
1f740 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 ite APIs, those
1f750 70 6f 73 74 66 69 78 65 64 20 77 69 74 68 20 22 postfixed with "
1f760 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 16" return.** UT
1f770 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 F-16 encoded str
1f780 69 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 72 20 ings, the other
1f790 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e functions return
1f7a0 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a UTF-8. {END}.**
1f7b0 0a 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20 61 .** These APIs a
1f7c0 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c re only availabl
1f7d0 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 e if the library
1f7e0 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 was compiled wi
1f7f0 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 th the.** [SQLIT
1f800 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f E_ENABLE_COLUMN_
1f810 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 METADATA] C-prep
1f820 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 rocessor symbol
1f830 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b defined..**.** {
1f840 41 31 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74 77 A13751}.** If tw
1f850 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 o or more thread
1f860 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f s call one or mo
1f870 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 re of these rout
1f880 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 ines against the
1f890 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 same.** prepare
1f8a0 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 d statement and
1f8b0 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 column at the sa
1f8c0 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 me time then the
1f8d0 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 results are.**
1f8e0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
1f8f0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
1f900 2a 20 5b 48 31 33 37 34 31 5d 20 5b 48 31 33 37 * [H13741] [H137
1f910 34 32 5d 20 5b 48 31 33 37 34 33 5d 20 5b 48 31 42] [H13743] [H1
1f920 33 37 34 34 5d 20 5b 48 31 33 37 34 35 5d 20 5b 3744] [H13745] [
1f930 48 31 33 37 34 36 5d 20 5b 48 31 33 37 34 38 5d H13746] [H13748]
1f940 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 .**.** If two or
1f950 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 more threads ca
1f960 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a ll one or more.*
1f970 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
1f980 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 n_database_name
1f990 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 | column metadat
1f9a0 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a a interfaces].**
1f9b0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 for the same [p
1f9c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
1f9d0 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f t] and result co
1f9e0 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 lumn.** at the s
1f9f0 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 ame time then th
1fa00 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e e results are un
1fa10 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 defined..*/.SQLI
1fa20 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 TE_API const cha
1fa30 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d r *sqlite3_colum
1fa40 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 n_database_name(
1fa50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
1fa60 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 t);.SQLITE_API c
1fa70 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
1fa80 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 e3_column_databa
1fa90 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 se_name16(sqlite
1faa0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 3_stmt*,int);.SQ
1fab0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 LITE_API const c
1fac0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c har *sqlite3_col
1fad0 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 umn_table_name(s
1fae0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
1faf0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
1fb00 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
1fb10 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 3_column_table_n
1fb20 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ame16(sqlite3_st
1fb30 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 mt*,int);.SQLITE
1fb40 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 _API const char
1fb50 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
1fb60 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 origin_name(sqli
1fb70 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
1fb80 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
1fb90 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 void *sqlite3_c
1fba0 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d olumn_origin_nam
1fbb0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 e16(sqlite3_stmt
1fbc0 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 *,int);../*.** C
1fbd0 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 API3REF: Declare
1fbe0 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 d Datatype Of A
1fbf0 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31 Query Result {H1
1fc00 33 37 36 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 3760} <S10700>.*
1fc10 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 *.** The first p
1fc20 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 arameter is a [p
1fc30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
1fc40 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 t]..** If this s
1fc50 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 tatement is a [S
1fc60 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 ELECT] statement
1fc70 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c and the Nth col
1fc80 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 umn of the.** re
1fc90 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 turned result se
1fca0 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 t of that [SELEC
1fcb0 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f T] is a table co
1fcc0 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 lumn (not an.**
1fcd0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 expression or su
1fce0 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 bquery) then the
1fcf0 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f declared type o
1fd00 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 f the table.** c
1fd10 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 olumn is returne
1fd20 64 2e 20 20 49 66 20 74 68 65 20 4e 74 68 20 63 d. If the Nth c
1fd30 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 olumn of the res
1fd40 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a ult set is an.**
1fd50 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 expression or s
1fd60 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 ubquery, then a
1fd70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 NULL pointer is
1fd80 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 returned..** The
1fd90 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 returned string
1fda0 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 is always UTF-8
1fdb0 20 65 6e 63 6f 64 65 64 2e 20 7b 45 4e 44 7d 0a encoded. {END}.
1fdc0 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c **.** For exampl
1fdd0 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 e, given the dat
1fde0 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a abase schema:.**
1fdf0 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 .** CREATE TABLE
1fe00 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b t1(c1 VARIANT);
1fe10 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 .**.** and the f
1fe20 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 ollowing stateme
1fe30 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 nt to be compile
1fe40 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 d:.**.** SELECT
1fe50 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 c1 + 1, c1 FROM
1fe60 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 t1;.**.** this r
1fe70 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 outine would ret
1fe80 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 urn the string "
1fe90 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 VARIANT" for the
1fea0 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a second result.*
1feb0 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c * column (i==1),
1fec0 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e and a NULL poin
1fed0 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 ter for the firs
1fee0 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 t result column
1fef0 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 (i==0)..**.** SQ
1ff00 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 Lite uses dynami
1ff10 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e c run-time typin
1ff20 67 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61 g. So just beca
1ff30 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 use a column.**
1ff40 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 is declared to c
1ff50 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 ontain a particu
1ff60 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f lar type does no
1ff70 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a t mean that the.
1ff80 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 ** data stored i
1ff90 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 n that column is
1ffa0 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 of the declared
1ffb0 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 type. SQLite i
1ffc0 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 s.** strongly ty
1ffd0 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 ped, but the typ
1ffe0 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e ing is dynamic n
1fff0 6f 74 20 73 74 61 74 69 63 2e 20 20 54 79 70 65 ot static. Type
20000 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 .** is associate
20010 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 d with individua
20020 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 l values, not wi
20030 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 th the container
20040 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c s.** used to hol
20050 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a d those values..
20060 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
20070 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 36 31 5d 20 ts:.** [H13761]
20080 5b 48 31 33 37 36 32 5d 20 5b 48 31 33 37 36 33 [H13762] [H13763
20090 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
200a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 const char *sqli
200b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 te3_column_declt
200c0 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ype(sqlite3_stmt
200d0 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 *,int);.SQLITE_A
200e0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 PI const void *s
200f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 qlite3_column_de
20100 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 cltype16(sqlite3
20110 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a _stmt*,int);../*
20120 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 .** CAPI3REF: Ev
20130 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 aluate An SQL St
20140 61 74 65 6d 65 6e 74 20 7b 48 31 33 32 30 30 7d atement {H13200}
20150 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S10000>.**.**
20160 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 After a [prepare
20170 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 d statement] has
20180 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 been prepared u
20190 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b sing either.** [
201a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
201b0 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 v2()] or [sqlite
201c0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
201d0 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 ] or one of the
201e0 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 legacy.** interf
201f0 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 aces [sqlite3_pr
20200 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c epare()] or [sql
20210 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
20220 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e ], this function
20230 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c .** must be call
20240 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 ed one or more t
20250 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 imes to evaluate
20260 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a the statement..
20270 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c **.** The detail
20280 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f s of the behavio
20290 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 r of the sqlite3
202a0 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 _step() interfac
202b0 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 e depend.** on w
202c0 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65 hether the state
202d0 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 ment was prepare
202e0 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 d using the newe
202f0 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 r "v2" interface
20300 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
20310 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b pare_v2()] and [
20320 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
20330 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6_v2()] or the o
20340 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 lder legacy.** i
20350 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 nterface [sqlite
20360 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 3_prepare()] and
20370 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
20380 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 e16()]. The use
20390 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 of the.** new "
203a0 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 v2" interface is
203b0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 recommended for
203c0 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e new application
203d0 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 s but the legacy
203e0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 .** interface wi
203f0 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 ll continue to b
20400 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a e supported..**.
20410 2a 2a 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 ** In the legacy
20420 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 interface, the
20430 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c return value wil
20440 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c l be either [SQL
20450 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 ITE_BUSY],.** [S
20460 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 QLITE_DONE], [SQ
20470 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 LITE_ROW], [SQLI
20480 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 TE_ERROR], or [S
20490 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a QLITE_MISUSE]..*
204a0 2a 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 * With the "v2"
204b0 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f interface, any o
204c0 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 f the other [res
204d0 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a ult codes] or.**
204e0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c [extended resul
204f0 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 t codes] might b
20500 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 e returned as we
20510 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 ll..**.** [SQLIT
20520 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 E_BUSY] means th
20530 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 at the database
20540 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c engine was unabl
20550 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 e to acquire the
20560 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 .** database loc
20570 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 ks it needs to d
20580 6f 20 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 o its job. If t
20590 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 he statement is
205a0 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 a [COMMIT].** or
205b0 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 occurs outside
205c0 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 of an explicit t
205d0 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e ransaction, then
205e0 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 you can retry t
205f0 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e he.** statement.
20600 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 If the stateme
20610 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d nt is not a [COM
20620 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 MIT] and occurs
20630 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c within a.** expl
20640 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e icit transaction
20650 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 then you should
20660 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 rollback the tr
20670 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 ansaction before
20680 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a .** continuing..
20690 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f **.** [SQLITE_DO
206a0 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 NE] means that t
206b0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 he statement has
206c0 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 finished execut
206d0 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 ing.** successfu
206e0 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 lly. sqlite3_st
206f0 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 ep() should not
20700 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 be called again
20710 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a on this virtual.
20720 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f ** machine witho
20730 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 ut first calling
20740 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
20750 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 )] to reset the
20760 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 virtual.** machi
20770 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 ne back to its i
20780 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a nitial state..**
20790 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 .** If the SQL s
207a0 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 tatement being e
207b0 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 xecuted returns
207c0 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b any data, then [
207d0 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 SQLITE_ROW].** i
207e0 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 s returned each
207f0 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f time a new row o
20800 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 f data is ready
20810 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 for processing b
20820 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e y the.** caller.
20830 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 The values may
20840 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e be accessed usin
20850 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 g the [column ac
20860 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e cess functions].
20870 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 .** sqlite3_step
20880 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 () is called aga
20890 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 in to retrieve t
208a0 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 he next row of d
208b0 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 ata..**.** [SQLI
208c0 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 TE_ERROR] means
208d0 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 that a run-time
208e0 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 error (such as a
208f0 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 constraint.** v
20900 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 iolation) has oc
20910 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 curred. sqlite3
20920 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e _step() should n
20930 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 ot be called aga
20940 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e in on.** the VM.
20950 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f More informatio
20960 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 n may be found b
20970 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 y calling [sqlit
20980 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a e3_errmsg()]..**
20990 20 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 With the legacy
209a0 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f interface, a mo
209b0 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f re specific erro
209c0 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d r code (for exam
209d0 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ple,.** [SQLITE_
209e0 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c INTERRUPT], [SQL
209f0 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 ITE_SCHEMA], [SQ
20a00 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 LITE_CORRUPT], a
20a10 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 nd so forth).**
20a20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 can be obtained
20a30 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 by calling [sqli
20a40 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 te3_reset()] on
20a50 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 the.** [prepared
20a60 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e statement]. In
20a70 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 the "v2" interf
20a80 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 ace,.** the more
20a90 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 specific error
20aa0 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 code is returned
20ab0 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c directly by sql
20ac0 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a ite3_step()..**.
20ad0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 ** [SQLITE_MISUS
20ae0 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 E] means that th
20af0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 e this routine w
20b00 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 as called inappr
20b10 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 opriately..** Pe
20b20 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c rhaps it was cal
20b30 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 led on a [prepar
20b40 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 ed statement] th
20b50 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 at has.** alread
20b60 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f y been [sqlite3_
20b70 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c finalize | final
20b80 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 ized] or on one
20b90 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 that had.** prev
20ba0 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 iously returned
20bb0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f [SQLITE_ERROR] o
20bc0 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e r [SQLITE_DONE].
20bd0 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a Or it could.**
20be0 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 be the case tha
20bf0 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 t the same datab
20c00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ase connection i
20c10 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 s being used by
20c20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 two or.** more t
20c30 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 hreads at the sa
20c40 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d me moment in tim
20c50 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 e..**.** <b>Goof
20c60 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 y Interface Aler
20c70 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 t:</b> In the le
20c80 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 gacy interface,
20c90 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 the sqlite3_step
20ca0 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 ().** API always
20cb0 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 returns a gener
20cc0 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b ic error code, [
20cd0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 SQLITE_ERROR], f
20ce0 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 ollowing any.**
20cf0 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e error other than
20d00 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 [SQLITE_BUSY] a
20d10 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 nd [SQLITE_MISUS
20d20 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 E]. You must ca
20d30 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 ll.** [sqlite3_r
20d40 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 eset()] or [sqli
20d50 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
20d60 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 in order to find
20d70 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 one of the.** s
20d80 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 pecific [error c
20d90 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 odes] that bette
20da0 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 r describes the
20db0 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d error..** We adm
20dc0 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20 it that this is
20dd0 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 a goofy design.
20de0 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 The problem has
20df0 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 been fixed.** w
20e00 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 ith the "v2" int
20e10 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 erface. If you
20e20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 prepare all of y
20e30 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e our SQL statemen
20e40 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 ts.** using eith
20e50 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 er [sqlite3_prep
20e60 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 are_v2()] or [sq
20e70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
20e80 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a v2()] instead.**
20e90 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b of the legacy [
20ea0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
20eb0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
20ec0 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 prepare16()] int
20ed0 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e erfaces,.** then
20ee0 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 the more specif
20ef0 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d ic [error codes]
20f00 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 are returned di
20f10 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c rectly.** by sql
20f20 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 ite3_step(). Th
20f30 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 e use of the "v2
20f40 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 " interface is r
20f50 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a ecommended..**.*
20f60 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
20f70 2a 2a 20 5b 48 31 33 32 30 32 5d 20 5b 48 31 35 ** [H13202] [H15
20f80 33 30 34 5d 20 5b 48 31 35 33 30 36 5d 20 5b 48 304] [H15306] [H
20f90 31 35 33 30 38 5d 20 5b 48 31 35 33 31 30 5d 0a 15308] [H15310].
20fa0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
20fb0 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 t sqlite3_step(s
20fc0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a qlite3_stmt*);..
20fd0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
20fe0 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e Number of column
20ff0 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 s in a result se
21000 74 20 7b 48 31 33 37 37 30 7d 20 3c 53 31 30 37 t {H13770} <S107
21010 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 00>.**.** Return
21020 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
21030 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20 63 75 values in the cu
21040 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 rrent row of the
21050 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a result set..**.
21060 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a ** Requirements:
21070 0a 2a 2a 20 5b 48 31 33 37 37 31 5d 20 5b 48 31 .** [H13771] [H1
21080 33 37 37 32 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 3772].*/.SQLITE_
21090 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
210a0 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 data_count(sqlit
210b0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b e3_stmt *pStmt);
210c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
210d0 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 : Fundamental Da
210e0 74 61 74 79 70 65 73 20 7b 48 31 30 32 36 35 7d tatypes {H10265}
210f0 20 3c 53 31 30 31 31 30 3e 3c 53 31 30 31 32 30 <S10110><S10120
21100 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 >.** KEYWORDS: S
21110 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a QLITE_TEXT.**.**
21120 20 7b 48 31 30 32 36 36 7d 20 45 76 65 72 79 20 {H10266} Every
21130 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 value in SQLite
21140 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 has one of five
21150 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 fundamental data
21160 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c types:.**.** <ul
21170 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 >.** <li> 64-bit
21180 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a signed integer.
21190 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 ** <li> 64-bit I
211a0 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 EEE floating poi
211b0 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 nt number.** <li
211c0 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e > string.** <li>
211d0 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 BLOB.** <li> NU
211e0 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 LL.** </ul> {END
211f0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f }.**.** These co
21200 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 nstants are code
21210 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 s for each of th
21220 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a ose types..**.**
21230 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 Note that the S
21240 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 QLITE_TEXT const
21250 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 ant was also use
21260 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 d in SQLite vers
21270 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 ion 2.** for a c
21280 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 ompletely differ
21290 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f ent meaning. So
212a0 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b ftware that link
212b0 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a s against both.*
212c0 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e * SQLite version
212d0 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 2 and SQLite ve
212e0 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 rsion 3 should u
212f0 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c se SQLITE3_TEXT,
21300 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 not.** SQLITE_T
21310 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 EXT..*/.#define
21320 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 SQLITE_INTEGER
21330 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
21340 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 _FLOAT 2.#def
21350 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 ine SQLITE_BLOB
21360 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4.#define SQ
21370 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a LITE_NULL 5.
21380 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 #ifdef SQLITE_TE
21390 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 XT.# undef SQLIT
213a0 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 E_TEXT.#else.# d
213b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 efine SQLITE_TEX
213c0 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 T 3.#endif.#
213d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 define SQLITE3_T
213e0 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a EXT 3../*.**
213f0 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c CAPI3REF: Resul
21400 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 t Values From A
21410 51 75 65 72 79 20 7b 48 31 33 38 30 30 7d 20 3c Query {H13800} <
21420 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f S10700>.** KEYWO
21430 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 RDS: {column acc
21440 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a ess functions}.*
21450 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
21460 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 nes form the "re
21470 73 75 6c 74 20 73 65 74 20 71 75 65 72 79 22 20 sult set query"
21480 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a interface..**.**
21490 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
214a0 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 return informati
214b0 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c on about a singl
214c0 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 e column of the
214d0 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c current.** resul
214e0 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 t row of a query
214f0 2e 20 20 49 6e 20 65 76 65 72 79 20 63 61 73 65 . In every case
21500 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
21510 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ent is a pointer
21520 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 .** to the [prep
21530 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
21540 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 that is being ev
21550 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 aluated (the [sq
21560 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 lite3_stmt*].**
21570 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 that was returne
21580 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
21590 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
215a0 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 one of its vari
215b0 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 ants).** and the
215c0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
215d0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 is the index of
215e0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 the column for
215f0 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f which informatio
21600 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 n.** should be r
21610 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 6c 65 eturned. The le
21620 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 ftmost column of
21630 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 the result set
21640 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e has the index 0.
21650 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 .**.** If the SQ
21660 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 L statement does
21670 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 not currently p
21680 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 oint to a valid
21690 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a row, or if the.*
216a0 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 * column index i
216b0 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 s out of range,
216c0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e the result is un
216d0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 defined..** Thes
216e0 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f e routines may o
216f0 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 nly be called wh
21700 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 en the most rece
21710 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 nt call to.** [s
21720 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 qlite3_step()] h
21730 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c as returned [SQL
21740 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 ITE_ROW] and nei
21750 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ther.** [sqlite3
21760 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 _reset()] nor [s
21770 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
21780 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c )] have been cal
21790 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 led subsequently
217a0 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 ..** If any of t
217b0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
217c0 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b e called after [
217d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
217e0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
217f0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 finalize()] or a
21800 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 fter [sqlite3_st
21810 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e ep()] has return
21820 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 ed.** something
21830 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 other than [SQLI
21840 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 TE_ROW], the res
21850 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e ults are undefin
21860 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 ed..** If [sqlit
21870 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 e3_step()] or [s
21880 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
21890 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 or [sqlite3_fina
218a0 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 lize()].** are c
218b0 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 alled from a dif
218c0 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 ferent thread wh
218d0 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 ile any of these
218e0 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 routines.** are
218f0 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 pending, then t
21900 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 he results are u
21910 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
21920 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 The sqlite3_colu
21930 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e mn_type() routin
21940 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a e returns the.**
21950 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 [SQLITE_INTEGER
21960 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 | datatype code
21970 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 ] for the initia
21980 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f l data type.** o
21990 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c f the result col
219a0 75 6d 6e 2e 20 20 54 68 65 20 72 65 74 75 72 6e umn. The return
219b0 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 ed value is one
219c0 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 of [SQLITE_INTEG
219d0 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ER],.** [SQLITE_
219e0 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f FLOAT], [SQLITE_
219f0 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 TEXT], [SQLITE_B
21a00 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 LOB], or [SQLITE
21a10 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c _NULL]. The val
21a20 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 ue.** returned b
21a30 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e y sqlite3_column
21a40 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 _type() is only
21a50 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f meaningful if no
21a60 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 type.** convers
21a70 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 ions have occurr
21a80 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 ed as described
21a90 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 below. After a
21aa0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c type conversion,
21ab0 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 .** the value re
21ac0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 turned by sqlite
21ad0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 3_column_type()
21ae0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 is undefined. F
21af0 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e uture.** version
21b00 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 s of SQLite may
21b10 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 change the behav
21b20 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 ior of sqlite3_c
21b30 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 olumn_type().**
21b40 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 following a type
21b50 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a conversion..**.
21b60 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 ** If the result
21b70 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 is a BLOB or UT
21b80 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 F-8 string then
21b90 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 the sqlite3_colu
21ba0 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f mn_bytes().** ro
21bb0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 utine returns th
21bc0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
21bd0 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f s in that BLOB o
21be0 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49 66 20 r string..** If
21bf0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 the result is a
21c00 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 UTF-16 string, t
21c10 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 hen sqlite3_colu
21c20 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 mn_bytes() conve
21c30 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e rts.** the strin
21c40 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 g to UTF-8 and t
21c50 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 hen returns the
21c60 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e number of bytes.
21c70 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c .** If the resul
21c80 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 t is a numeric v
21c90 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 alue then sqlite
21ca0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
21cb0 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 uses.** [sqlite
21cc0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 3_snprintf()] to
21cd0 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 convert that va
21ce0 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 lue to a UTF-8 s
21cf0 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e tring and return
21d00 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 s.** the number
21d10 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 of bytes in that
21d20 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 string..** The
21d30 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 64 value returned d
21d40 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 oes not include
21d50 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 the zero termina
21d60 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a 2a tor at the end.*
21d70 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e * of the string.
21d80 20 20 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 For clarity: t
21d90 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
21da0 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 d is the number
21db0 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 of.** bytes in t
21dc0 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 he string, not t
21dd0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 he number of cha
21de0 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 53 racters..**.** S
21df0 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 trings returned
21e00 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d by sqlite3_colum
21e10 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c n_text() and sql
21e20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
21e30 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 16(),.** even em
21e40 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 pty strings, are
21e50 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 74 65 72 always zero ter
21e60 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20 72 65 minated. The re
21e70 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 turn.** value fr
21e80 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d om sqlite3_colum
21e90 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a n_blob() for a z
21ea0 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 ero-length BLOB
21eb0 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 0a is an arbitrary.
21ec0 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f 73 73 ** pointer, poss
21ed0 69 62 6c 79 20 65 76 65 6e 20 61 20 4e 55 4c 4c ibly even a NULL
21ee0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 pointer..**.**
21ef0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 The sqlite3_colu
21f00 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 6f 75 mn_bytes16() rou
21f10 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 tine is similar
21f20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d to sqlite3_colum
21f30 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 n_bytes().** but
21f40 20 6c 65 61 76 65 73 20 74 68 65 20 72 65 73 75 leaves the resu
21f50 6c 74 20 69 6e 20 55 54 46 2d 31 36 20 69 6e 20 lt in UTF-16 in
21f60 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
21f70 72 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46 r instead of UTF
21f80 2d 38 2e 0a 2a 2a 20 54 68 65 20 7a 65 72 6f 20 -8..** The zero
21f90 74 65 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f terminator is no
21fa0 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 t included in th
21fb0 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 is count..**.**
21fc0 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 The object retur
21fd0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ned by [sqlite3_
21fe0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 column_value()]
21ff0 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 is an.** [unprot
22000 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
22010 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e lue] object. An
22020 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c unprotected sql
22030 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
22040 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 t.** may only be
22050 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 used with [sqli
22060 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 te3_bind_value()
22070 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 ] and [sqlite3_r
22080 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a esult_value()]..
22090 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f ** If the [unpro
220a0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
220b0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 alue] object ret
220c0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c urned by.** [sql
220d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 ite3_column_valu
220e0 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 e()] is used in
220f0 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 any other way, i
22100 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a ncluding calls.*
22110 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 * to routines li
22120 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ke [sqlite3_valu
22130 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 e_int()], [sqlit
22140 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d e3_value_text()]
22150 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 ,.** or [sqlite3
22160 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c _value_bytes()],
22170 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 then the behavi
22180 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e or is undefined.
22190 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
221a0 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f tines attempt to
221b0 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c convert the val
221c0 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 ue where appropr
221d0 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 iate. For.** ex
221e0 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e ample, if the in
221f0 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 ternal represent
22200 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 ation is FLOAT a
22210 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 nd a text result
22220 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 .** is requested
22230 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 , [sqlite3_snpri
22240 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 ntf()] is used i
22250 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 nternally to per
22260 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 form the.** conv
22270 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 ersion automatic
22280 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c 6f ally. The follo
22290 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 wing table detai
222a0 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f ls the conversio
222b0 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 ns.** that are a
222c0 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 pplied:.**.** <b
222d0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 lockquote>.** <t
222e0 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e able border="1">
222f0 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 .** <tr><th> Int
22300 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 ernal<br>Type <t
22310 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e h> Requested<br>
22320 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 Type <th> Conve
22330 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e rsion.**.** <tr>
22340 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 <td> NULL <t
22350 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 d> INTEGER <td
22360 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a > Result is 0.**
22370 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 <tr><td> NULL
22380 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 <td> FLOAT
22390 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 <td> Result is
223a0 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 0.0.** <tr><td>
223b0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 NULL <td>
223c0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 TEXT <td> Re
223d0 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 sult is NULL poi
223e0 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e nter.** <tr><td>
223f0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 NULL <td>
22400 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 BLOB <td> Re
22410 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 sult is NULL poi
22420 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e nter.** <tr><td>
22430 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 INTEGER <td>
22440 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f FLOAT <td> Co
22450 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 nvert from integ
22460 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c er to float.** <
22470 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 tr><td> INTEGER
22480 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 <td> TEXT
22490 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 <td> ASCII rende
224a0 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 ring of the inte
224b0 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 ger.** <tr><td>
224c0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 INTEGER <td>
224d0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d BLOB <td> Sam
224e0 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 e as INTEGER->TE
224f0 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 XT.** <tr><td>
22500 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 FLOAT <td> INT
22510 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 EGER <td> Conv
22520 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 ert from float t
22530 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 o integer.** <tr
22540 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c ><td> FLOAT <
22550 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 td> TEXT <t
22560 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 d> ASCII renderi
22570 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a ng of the float.
22580 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f ** <tr><td> FLO
22590 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 AT <td> BLOB
225a0 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 <td> Same as
225b0 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 FLOAT->TEXT.**
225c0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 <tr><td> TEXT
225d0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 <td> INTEGER
225e0 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29 <td> Use atoi()
225f0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 .** <tr><td> TE
22600 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 XT <td> FLOA
22610 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 T <td> Use at
22620 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e of().** <tr><td>
22630 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 TEXT <td>
22640 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f BLOB <td> No
22650 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c change.** <tr><
22660 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 td> BLOB <td
22670 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e > INTEGER <td>
22680 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 Convert to TEXT
22690 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29 then use atoi()
226a0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c .** <tr><td> BL
226b0 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 OB <td> FLOA
226c0 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 T <td> Conver
226d0 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 t to TEXT then u
226e0 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 se atof().** <tr
226f0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c ><td> BLOB <
22700 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 td> TEXT <t
22710 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 d> Add a zero te
22720 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 rminator if need
22730 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a ed.** </table>.*
22740 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a * </blockquote>.
22750 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 **.** The table
22760 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 above makes refe
22770 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 rence to standar
22780 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 d C library func
22790 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 tions atoi().**
227a0 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c and atof(). SQL
227b0 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 ite does not rea
227c0 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75 lly use these fu
227d0 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 nctions. It has
227e0 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 its.** own equi
227f0 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 valent internal
22800 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 routines. The a
22810 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 toi() and atof()
22820 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 names are.** us
22830 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 ed in the table
22840 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 for brevity and
22850 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65 because they are
22860 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 familiar to mos
22870 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 t.** C programme
22880 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 rs..**.** Note t
22890 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f hat when type co
228a0 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c nversions occur,
228b0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e pointers return
228c0 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 ed by prior.** c
228d0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
228e0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 column_blob(), s
228f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
22900 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 xt(), and/or.**
22910 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
22920 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 ext16() may be i
22930 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 nvalidated..** T
22940 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 ype conversions
22950 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 and pointer inva
22960 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 lidations might
22970 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 occur.** in the
22980 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a following cases:
22990 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
229a0 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 li> The initial
229b0 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f content is a BLO
229c0 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f B and sqlite3_co
229d0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a lumn_text() or.*
229e0 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 * sqlite3_c
229f0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 olumn_text16() i
22a00 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 s called. A zer
22a10 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 o-terminator mig
22a20 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 ht.** need
22a30 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 to be added to t
22a40 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a he string.</li>.
22a50 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 ** <li> The init
22a60 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 ial content is U
22a70 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 TF-8 text and sq
22a80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
22a90 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 es16() or.**
22aa0 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e sqlite3_column
22ab0 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c _text16() is cal
22ac0 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e led. The conten
22ad0 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 t must be conver
22ae0 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 ted.** to U
22af0 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c TF-16.</li>.** <
22b00 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 li> The initial
22b10 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 content is UTF-1
22b20 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 6 text and sqlit
22b30 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
22b40 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c ) or.** sql
22b50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
22b60 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 () is called. T
22b70 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 he content must
22b80 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 be converted.**
22b90 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f to UTF-8.</
22ba0 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a li>.** </ul>.**.
22bb0 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 ** Conversions b
22bc0 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 etween UTF-16be
22bd0 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 and UTF-16le are
22be0 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 always done in
22bf0 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 place and do.**
22c00 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 not invalidate a
22c10 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 prior pointer,
22c20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 though of course
22c30 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 the content of
22c40 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 the buffer.** th
22c50 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 at the prior poi
22c60 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f 20 77 nter points to w
22c70 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f ill have been mo
22c80 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b dified. Other k
22c90 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 inds.** of conve
22ca0 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 rsion are done i
22cb0 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 n place when it
22cc0 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 is possible, but
22cd0 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a sometimes they.
22ce0 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 ** are not possi
22cf0 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 ble and in those
22d00 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 cases prior poi
22d10 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 nters are invali
22d20 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 dated..**.** The
22d30 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 safest and easi
22d40 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 est to remember
22d50 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 policy is to inv
22d60 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e oke these routin
22d70 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 es.** in one of
22d80 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 the following wa
22d90 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a ys:.**.** <ul>.*
22da0 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 * <li>sqlite3_c
22db0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c olumn_text() fol
22dc0 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 lowed by sqlite3
22dd0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c _column_bytes()<
22de0 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c /li>.** <li>sql
22df0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 ite3_column_blob
22e00 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 () followed by s
22e10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
22e20 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c tes()</li>.** <
22e30 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d li>sqlite3_colum
22e40 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f n_text16() follo
22e50 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 wed by sqlite3_c
22e60 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c olumn_bytes16()<
22e70 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a /li>.** </ul>.**
22e80 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 .** In other wor
22e90 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 ds, you should c
22ea0 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 all sqlite3_colu
22eb0 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 mn_text(),.** sq
22ec0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
22ed0 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f b(), or sqlite3_
22ee0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 column_text16()
22ef0 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 first to force t
22f00 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 he result.** int
22f10 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f o the desired fo
22f20 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b rmat, then invok
22f30 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
22f40 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 _bytes() or.** s
22f50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
22f60 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 tes16() to find
22f70 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
22f80 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 result. Do not
22f90 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 mix calls.** to
22fa0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
22fb0 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 ext() or sqlite3
22fc0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 _column_blob() w
22fd0 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 ith calls to.**
22fe0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
22ff0 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f ytes16(), and do
23000 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 not mix calls t
23010 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e o sqlite3_column
23020 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 _text16().** wit
23030 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 h calls to sqlit
23040 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
23050 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 )..**.** The poi
23060 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 nters returned a
23070 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 re valid until a
23080 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e type conversion
23090 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 occurs as.** de
230a0 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f scribed above, o
230b0 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 r until [sqlite3
230c0 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c _step()] or [sql
230d0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 ite3_reset()] or
230e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e .** [sqlite3_fin
230f0 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c alize()] is call
23100 65 64 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 ed. The memory
23110 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f space used to ho
23120 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e ld strings.** an
23130 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 d BLOBs is freed
23140 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 automatically.
23150 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 Do <b>not</b> p
23160 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 ass the pointers
23170 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 returned.** [sq
23180 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
23190 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 b()], [sqlite3_c
231a0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 olumn_text()], e
231b0 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c tc. into.** [sql
231c0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a ite3_free()]..**
231d0 0a 2a 2a 20 49 66 20 61 20 6d 65 6d 6f 72 79 20 .** If a memory
231e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 allocation error
231f0 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 occurs during t
23200 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 he evaluation of
23210 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 any.** of these
23220 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 routines, a def
23230 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 ault value is re
23240 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 turned. The def
23250 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 ault value.** is
23260 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 either the inte
23270 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 ger 0, the float
23280 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 ing point number
23290 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 0.0, or a NULL.
232a0 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 ** pointer. Sub
232b0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f sequent calls to
232c0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 [sqlite3_errcod
232d0 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e e()] will return
232e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 .** [SQLITE_NOME
232f0 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 M]..**.** Requir
23300 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 38 ements:.** [H138
23310 30 33 5d 20 5b 48 31 33 38 30 36 5d 20 5b 48 31 03] [H13806] [H1
23320 33 38 30 39 5d 20 5b 48 31 33 38 31 32 5d 20 5b 3809] [H13812] [
23330 48 31 33 38 31 35 5d 20 5b 48 31 33 38 31 38 5d H13815] [H13818]
23340 20 5b 48 31 33 38 32 31 5d 20 5b 48 31 33 38 32 [H13821] [H1382
23350 34 5d 0a 2a 2a 20 5b 48 31 33 38 32 37 5d 20 5b 4].** [H13827] [
23360 48 31 33 38 33 30 5d 0a 2a 2f 0a 53 51 4c 49 54 H13830].*/.SQLIT
23370 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 E_API const void
23380 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
23390 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 _blob(sqlite3_st
233a0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
233b0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
233c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
233d0 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 tes(sqlite3_stmt
233e0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 *, int iCol);.SQ
233f0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
23400 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
23410 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 s16(sqlite3_stmt
23420 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 *, int iCol);.SQ
23430 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 LITE_API double
23440 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
23450 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 ouble(sqlite3_st
23460 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
23470 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
23480 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e qlite3_column_in
23490 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c t(sqlite3_stmt*,
234a0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 int iCol);.SQLI
234b0 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 TE_API sqlite3_i
234c0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c nt64 sqlite3_col
234d0 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 umn_int64(sqlite
234e0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
234f0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 l);.SQLITE_API c
23500 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 onst unsigned ch
23510 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ar *sqlite3_colu
23520 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f mn_text(sqlite3_
23530 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
23540 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e ;.SQLITE_API con
23550 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
23560 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 _column_text16(s
23570 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
23580 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f t iCol);.SQLITE_
23590 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
235a0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 column_type(sqli
235b0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
235c0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 Col);.SQLITE_API
235d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a sqlite3_value *
235e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 sqlite3_column_v
235f0 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d alue(sqlite3_stm
23600 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a t*, int iCol);..
23610 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
23620 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 Destroy A Prepar
23630 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a ed Statement Obj
23640 65 63 74 20 7b 48 31 33 33 30 30 7d 20 3c 53 37 ect {H13300} <S7
23650 30 33 30 30 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0300><S30100>.**
23660 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
23670 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 finalize() funct
23680 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f ion is called to
23690 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 delete a [prepa
236a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a red statement]..
236b0 2a 2a 20 49 66 20 74 68 65 20 73 74 61 74 65 6d ** If the statem
236c0 65 6e 74 20 77 61 73 20 65 78 65 63 75 74 65 64 ent was executed
236d0 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 6f 72 successfully or
236e0 20 6e 6f 74 20 65 78 65 63 75 74 65 64 20 61 74 not executed at
236f0 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 all, then.** SQ
23700 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 LITE_OK is retur
23710 6e 65 64 2e 20 49 66 20 65 78 65 63 75 74 69 6f ned. If executio
23720 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 n of the stateme
23730 6e 74 20 66 61 69 6c 65 64 20 74 68 65 6e 20 61 nt failed then a
23740 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 n.** [error code
23750 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 ] or [extended e
23760 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 rror code] is re
23770 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 turned..**.** Th
23780 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 is routine can b
23790 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 e called at any
237a0 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 74 68 65 point during the
237b0 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 execution of th
237c0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 e.** [prepared s
237d0 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 66 20 74 tatement]. If t
237e0 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 he virtual machi
237f0 6e 65 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f ne has not.** co
23800 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f mpleted executio
23810 6e 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74 n when this rout
23820 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 ine is called, t
23830 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 hat is like.** e
23840 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 ncountering an e
23850 72 72 6f 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 rror or an [sqli
23860 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 te3_interrupt |
23870 69 6e 74 65 72 72 75 70 74 5d 2e 0a 2a 2a 20 49 interrupt]..** I
23880 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61 74 65 ncomplete update
23890 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64 20 s may be rolled
238a0 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73 61 63 back and transac
238b0 74 69 6f 6e 73 20 63 61 6e 63 65 6c 65 64 2c 0a tions canceled,.
238c0 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 ** depending on
238d0 74 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 the circumstance
238e0 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 65 s, and the.** [e
238f0 72 72 6f 72 20 63 6f 64 65 5d 20 72 65 74 75 72 rror code] retur
23900 6e 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c ned will be [SQL
23910 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a ITE_ABORT]..**.*
23920 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
23930 2a 2a 20 5b 48 31 31 33 30 32 5d 20 5b 48 31 31 ** [H11302] [H11
23940 33 30 34 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 304].*/.SQLITE_A
23950 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 PI int sqlite3_f
23960 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f inalize(sqlite3_
23970 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f stmt *pStmt);../
23980 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
23990 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 eset A Prepared
239a0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 Statement Object
239b0 20 7b 48 31 33 33 33 30 7d 20 3c 53 37 30 33 30 {H13330} <S7030
239c0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 0>.**.** The sql
239d0 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e ite3_reset() fun
239e0 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 ction is called
239f0 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 to reset a [prep
23a00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a ared statement].
23a10 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 ** object back t
23a20 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 o its initial st
23a30 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 ate, ready to be
23a40 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a re-executed..**
23a50 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 Any SQL stateme
23a60 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 nt variables tha
23a70 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 t had values bou
23a80 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 nd to them using
23a90 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 .** the [sqlite3
23aa0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c _bind_blob | sql
23ab0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 ite3_bind_*() AP
23ac0 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 I] retain their
23ad0 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b values..** Use [
23ae0 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 sqlite3_clear_bi
23af0 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 ndings()] to res
23b00 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e et the bindings.
23b10 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 32 7d 20 .**.** {H11332}
23b20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 The [sqlite3_res
23b30 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 et(S)] interface
23b40 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 resets the [pre
23b50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
23b60 20 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 S.** b
23b70 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e ack to the begin
23b80 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 ning of its prog
23b90 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 ram..**.** {H113
23ba0 33 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 34} If the most
23bb0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b recent call to [
23bc0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d sqlite3_step(S)]
23bd0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 for the.**
23be0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 [prepared s
23bf0 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 tatement] S retu
23c00 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 rned [SQLITE_ROW
23c10 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e ] or [SQLITE_DON
23c20 45 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 E],.**
23c30 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 or if [sqlite3_s
23c40 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 tep(S)] has neve
23c50 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 r before been ca
23c60 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 20 20 lled on S,.**
23c70 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c then [sql
23c80 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 ite3_reset(S)] r
23c90 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f eturns [SQLITE_O
23ca0 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 K]..**.** {H1133
23cb0 36 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 6} If the most r
23cc0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 ecent call to [s
23cd0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 qlite3_step(S)]
23ce0 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 for the.**
23cf0 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 [prepared st
23d00 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 atement] S indic
23d10 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 ated an error, t
23d20 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 hen.**
23d30 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 [sqlite3_reset(S
23d40 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 )] returns an ap
23d50 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 propriate [error
23d60 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 code]..**.** {H
23d70 31 31 33 33 38 7d 20 54 68 65 20 5b 73 71 6c 69 11338} The [sqli
23d80 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e te3_reset(S)] in
23d90 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 terface does not
23da0 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 change the valu
23db0 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f es.** o
23dc0 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 f any [sqlite3_b
23dd0 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 ind_blob|binding
23de0 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 s] on the [prepa
23df0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
23e00 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
23e10 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 int sqlite3_rese
23e20 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a t(sqlite3_stmt *
23e30 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 pStmt);../*.** C
23e40 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 API3REF: Create
23e50 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 Or Redefine SQL
23e60 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 31 30 Functions {H1610
23e70 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 0} <S20200>.** K
23e80 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 EYWORDS: {functi
23e90 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 on creation rout
23ea0 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 ines}.** KEYWORD
23eb0 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d S: {application-
23ec0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
23ed0 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 tion}.** KEYWORD
23ee0 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d S: {application-
23ef0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
23f00 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 tions}.**.** The
23f10 73 65 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 se two functions
23f20 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b (collectively k
23f30 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f nown as "functio
23f40 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 n creation routi
23f50 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 nes").** are use
23f60 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e d to add SQL fun
23f70 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 ctions or aggreg
23f80 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 ates or to redef
23f90 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 ine the behavior
23fa0 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 .** of existing
23fb0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 SQL functions or
23fc0 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 aggregates. Th
23fd0 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 e only differenc
23fe0 65 20 62 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a e between the.**
23ff0 20 74 77 6f 20 69 73 20 74 68 61 74 20 74 68 65 two is that the
24000 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
24010 72 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 r, the name of t
24020 68 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63 he (scalar) func
24030 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 tion or.** aggre
24040 67 61 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 gate, is encoded
24050 20 69 6e 20 55 54 46 2d 38 20 66 6f 72 20 73 71 in UTF-8 for sq
24060 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
24070 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d ction() and UTF-
24080 31 36 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 16.** for sqlite
24090 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
240a0 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 n16()..**.** The
240b0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
240c0 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 is the [databas
240d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f e connection] to
240e0 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a which the SQL.*
240f0 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f * function is to
24100 20 62 65 20 61 64 64 65 64 2e 20 20 49 66 20 61 be added. If a
24110 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 61 6d 20 single program
24120 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f uses more than o
24130 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 ne database.** c
24140 6f 6e 6e 65 63 74 69 6f 6e 20 69 6e 74 65 72 6e onnection intern
24150 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c 20 66 ally, then SQL f
24160 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 unctions must be
24170 20 61 64 64 65 64 20 69 6e 64 69 76 69 64 75 61 added individua
24180 6c 6c 79 20 74 6f 0a 2a 2a 20 65 61 63 68 20 64 lly to.** each d
24190 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
241a0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 on..**.** The se
241b0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 cond parameter i
241c0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
241d0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 e SQL function t
241e0 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a o be created or.
241f0 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 54 ** redefined. T
24200 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 he length of the
24210 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 name is limited
24220 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20 65 to 255 bytes, e
24230 78 63 6c 75 73 69 76 65 20 6f 66 0a 2a 2a 20 74 xclusive of.** t
24240 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 he zero-terminat
24250 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 or. Note that t
24260 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c he name length l
24270 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65 73 imit is in bytes
24280 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74 , not.** charact
24290 65 72 73 2e 20 20 41 6e 79 20 61 74 74 65 6d 70 ers. Any attemp
242a0 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 t to create a fu
242b0 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f nction with a lo
242c0 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c nger name.** wil
242d0 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c l result in [SQL
242e0 49 54 45 5f 45 52 52 4f 52 5d 20 62 65 69 6e 67 ITE_ERROR] being
242f0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
24300 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d The third param
24310 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 eter (nArg).** i
24320 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
24330 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 arguments that t
24340 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 he SQL function
24350 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 or.** aggregate
24360 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20 70 takes. If this p
24370 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 arameter is -1,
24380 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e then the SQL fun
24390 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 ction or.** aggr
243a0 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 egate may take a
243b0 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 ny number of arg
243c0 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 uments between 0
243d0 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a and the limit.*
243e0 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 * set by [sqlite
243f0 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 3_limit]([SQLITE
24400 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f _LIMIT_FUNCTION_
24410 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 ARG]). If the t
24420 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 hird.** paramete
24430 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d r is less than -
24440 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 1 or greater tha
24450 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 n 127 then the b
24460 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e ehavior is.** un
24470 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 defined..**.** T
24480 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
24490 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 ter, eTextRep, s
244a0 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a pecifies what.**
244b0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 [SQLITE_UTF8 |
244c0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 text encoding] t
244d0 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e his SQL function
244e0 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 prefers for.**
244f0 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 its parameters.
24500 20 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f Any SQL functio
24510 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e n implementation
24520 20 73 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 20 should be able
24530 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20 to work.** work
24540 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d with UTF-8, UTF-
24550 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 16le, or UTF-16b
24560 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 e. But some imp
24570 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 lementations may
24580 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 be.** more effi
24590 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 cient with one e
245a0 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f ncoding than ano
245b0 74 68 65 72 2e 20 20 41 6e 20 61 70 70 6c 69 63 ther. An applic
245c0 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 ation may.** inv
245d0 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 oke sqlite3_crea
245e0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 te_function() or
245f0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
24600 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c function16() mul
24610 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 tiple.** times w
24620 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e ith the same fun
24630 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64 ction but with d
24640 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20 ifferent values
24650 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 of eTextRep..**
24660 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d When multiple im
24670 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 plementations of
24680 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 the same functi
24690 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 on are available
246a0 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c , SQLite.** will
246b0 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 pick the one th
246c0 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 at involves the
246d0 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 least amount of
246e0 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e data conversion.
246f0 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 .** If there is
24700 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d only a single im
24710 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 plementation whi
24720 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 ch does not care
24730 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e what text.** en
24740 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 coding is used,
24750 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 then the fourth
24760 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 argument should
24770 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e be [SQLITE_ANY].
24780 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 .**.** The fifth
24790 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e parameter is an
247a0 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 arbitrary point
247b0 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 er. The impleme
247c0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a ntation of the.*
247d0 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 * function can g
247e0 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 ain access to th
247f0 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 is pointer using
24800 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 [sqlite3_user_d
24810 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 ata()]..**.** Th
24820 65 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74 e seventh, eight
24830 68 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 h and ninth para
24840 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 meters, xFunc, x
24850 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c Step and xFinal,
24860 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 are.** pointers
24870 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 to C-language f
24880 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d unctions that im
24890 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 plement the SQL
248a0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 function or.** a
248b0 67 67 72 65 67 61 74 65 2e 20 41 20 73 63 61 6c ggregate. A scal
248c0 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 ar SQL function
248d0 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c requires an impl
248e0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 ementation of th
248f0 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 e xFunc.** callb
24900 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 ack only, NULL p
24910 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62 ointers should b
24920 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 e passed as the
24930 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c xStep and xFinal
24940 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 .** parameters.
24950 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c An aggregate SQL
24960 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 function requir
24970 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 es an implementa
24980 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a tion of xStep.**
24990 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 and xFinal and
249a0 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 NULL should be p
249b0 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e assed for xFunc.
249c0 20 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 To delete an ex
249d0 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 isting.** SQL fu
249e0 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 nction or aggreg
249f0 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 ate, pass NULL f
24a00 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e or all three fun
24a10 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e ction callbacks.
24a20 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65 72 .**.** It is per
24a30 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 mitted to regist
24a40 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c er multiple impl
24a50 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 ementations of t
24a60 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 he same.** funct
24a70 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 ions with the sa
24a80 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 me name but with
24a90 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e either differin
24aa0 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 g numbers of.**
24ab0 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 arguments or dif
24ac0 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 fering preferred
24ad0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e text encodings.
24ae0 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 SQLite will us
24af0 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 e.** the impleme
24b00 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 ntation that mos
24b10 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 t closely matche
24b20 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 s the way in whi
24b30 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 ch the.** SQL fu
24b40 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 nction is used.
24b50 20 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c A function impl
24b60 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 ementation with
24b70 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a a non-negative.*
24b80 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 * nArg parameter
24b90 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 is a better mat
24ba0 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 ch than a functi
24bb0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f on implementatio
24bc0 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 n with.** a nega
24bd0 74 69 76 65 20 6e 41 72 67 2e 20 20 41 20 66 75 tive nArg. A fu
24be0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 nction where the
24bf0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 preferred text
24c00 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 encoding.** matc
24c10 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 hes the database
24c20 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 encoding is a b
24c30 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 etter.** match t
24c40 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 han a function w
24c50 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e here the encodin
24c60 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 g is different.
24c70 20 0a 2a 2a 20 41 20 66 75 6e 63 74 69 6f 6e 20 .** A function
24c80 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 where the encodi
24c90 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 ng difference is
24ca0 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 between UTF16le
24cb0 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 and UTF16be.**
24cc0 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 is a closer matc
24cd0 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f h than a functio
24ce0 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f n where the enco
24cf0 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 ding difference
24d00 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 is.** between UT
24d10 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a F8 and UTF16..**
24d20 0a 2a 2a 20 42 75 69 6c 74 2d 69 6e 20 66 75 6e .** Built-in fun
24d30 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 ctions may be ov
24d40 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 erloaded by new
24d50 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
24d60 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a ned functions..*
24d70 2a 20 54 68 65 20 66 69 72 73 74 20 61 70 70 6c * The first appl
24d80 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
24d90 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 function with a
24da0 67 69 76 65 6e 20 6e 61 6d 65 20 6f 76 65 72 72 given name overr
24db0 69 64 65 73 20 61 6c 6c 0a 2a 2a 20 62 75 69 6c ides all.** buil
24dc0 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 69 t-in functions i
24dd0 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 n the same [data
24de0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
24df0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e with the same n
24e00 61 6d 65 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 ame..** Subseque
24e10 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 nt application-d
24e20 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 efined functions
24e30 20 6f 66 20 74 68 65 20 73 61 6d 65 20 6e 61 6d of the same nam
24e40 65 20 6f 6e 6c 79 20 6f 76 65 72 72 69 64 65 20 e only override
24e50 0a 2a 2a 20 70 72 69 6f 72 20 61 70 70 6c 69 63 .** prior applic
24e60 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
24e70 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 nctions that are
24e80 20 61 6e 20 65 78 61 63 74 20 6d 61 74 63 68 20 an exact match
24e90 66 6f 72 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 for the.** numbe
24ea0 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20 r of parameters
24eb0 61 6e 64 20 70 72 65 66 65 72 72 65 64 20 65 6e and preferred en
24ec0 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 41 6e coding..**.** An
24ed0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
24ee0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 ined function is
24ef0 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 permitted to ca
24f00 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 ll other.** SQLi
24f10 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 te interfaces.
24f20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 However, such ca
24f30 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 lls must not.**
24f40 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 close the databa
24f50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f se connection no
24f60 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 r finalize or re
24f70 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 set the prepared
24f80 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e .** statement in
24f90 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 which the funct
24fa0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a ion is running..
24fb0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
24fc0 74 73 3a 0a 2a 2a 20 5b 48 31 36 31 30 33 5d 20 ts:.** [H16103]
24fd0 5b 48 31 36 31 30 36 5d 20 5b 48 31 36 31 30 39 [H16106] [H16109
24fe0 5d 20 5b 48 31 36 31 31 32 5d 20 5b 48 31 36 31 ] [H16112] [H161
24ff0 31 38 5d 20 5b 48 31 36 31 32 31 5d 20 5b 48 31 18] [H16121] [H1
25000 36 31 32 37 5d 0a 2a 2a 20 5b 48 31 36 31 33 30 6127].** [H16130
25010 5d 20 5b 48 31 36 31 33 33 5d 20 5b 48 31 36 31 ] [H16133] [H161
25020 33 36 5d 20 5b 48 31 36 31 33 39 5d 20 5b 48 31 36] [H16139] [H1
25030 36 31 34 32 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 6142].*/.SQLITE_
25040 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
25050 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
25060 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a . sqlite3 *db,.
25070 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 const char *zF
25080 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 unctionName,. i
25090 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 nt nArg,. int e
250a0 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 TextRep,. void
250b0 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a *pApp,. void (*
250c0 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 xFunc)(sqlite3_c
250d0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 ontext*,int,sqli
250e0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 te3_value**),.
250f0 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 void (*xStep)(sq
25100 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 lite3_context*,i
25110 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt,sqlite3_value
25120 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 **),. void (*xF
25130 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f inal)(sqlite3_co
25140 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 ntext*).);.SQLIT
25150 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
25160 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
25170 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a n16(. sqlite3 *
25180 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 db,. const void
25190 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c *zFunctionName,
251a0 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 . int nArg,. i
251b0 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 nt eTextRep,. v
251c0 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 oid *pApp,. voi
251d0 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 d (*xFunc)(sqlit
251e0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c e3_context*,int,
251f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 sqlite3_value**)
25200 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 ,. void (*xStep
25210 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 )(sqlite3_contex
25220 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 t*,int,sqlite3_v
25230 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 alue**),. void
25240 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 (*xFinal)(sqlite
25250 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 3_context*).);..
25260 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
25270 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 20 7b Text Encodings {
25280 48 31 30 32 36 37 7d 20 3c 53 35 30 32 30 30 3e H10267} <S50200>
25290 20 3c 48 31 36 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 <H16100>.**.**
252a0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 These constant d
252b0 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f efine integer co
252c0 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 des that represe
252d0 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a nt the various.*
252e0 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 * text encodings
252f0 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 supported by SQ
25300 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 Lite..*/.#define
25310 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 SQLITE_UTF8
25320 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 1.#define
25330 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 SQLITE_UTF16LE
25340 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 2.#define
25350 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 SQLITE_UTF16BE
25360 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 3.#define
25370 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 SQLITE_UTF16
25380 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 4 /* U
25390 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f se native byte o
253a0 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 rder */.#define
253b0 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 SQLITE_ANY
253c0 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 5 /* sq
253d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
253e0 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 ction only */.#d
253f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 efine SQLITE_UTF
25400 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 16_ALIGNED 8
25410 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 /* sqlite3_crea
25420 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c te_collation onl
25430 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 y */../*.** CAPI
25440 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 3REF: Deprecated
25450 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 Functions.** DE
25460 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 PRECATED.**.** T
25470 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 hese functions a
25480 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e re [deprecated].
25490 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 In order to ma
254a0 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 intain.** backwa
254b0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 rds compatibilit
254c0 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 y with older cod
254d0 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f e, these functio
254e0 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 ns continue .**
254f0 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e to be supported.
25500 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 However, new a
25510 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 pplications shou
25520 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 ld avoid.** the
25530 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e use of these fun
25540 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 ctions. To help
25550 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c encourage peopl
25560 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 e to avoid.** us
25570 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 ing these functi
25580 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 ons, we are not
25590 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f going to tell yo
255a0 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a u what they do..
255b0 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 */.#ifndef SQLIT
255c0 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 E_OMIT_DEPRECATE
255d0 44 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c D.SQLITE_API SQL
255e0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 ITE_DEPRECATED i
255f0 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 nt sqlite3_aggre
25600 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 gate_count(sqlit
25610 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 e3_context*);.SQ
25620 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
25630 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 DEPRECATED int s
25640 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 qlite3_expired(s
25650 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 qlite3_stmt*);.S
25660 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
25670 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 _DEPRECATED int
25680 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 sqlite3_transfer
25690 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 _bindings(sqlite
256a0 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 3_stmt*, sqlite3
256b0 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f _stmt*);.SQLITE_
256c0 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 API SQLITE_DEPRE
256d0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 CATED int sqlite
256e0 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 3_global_recover
256f0 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 (void);.SQLITE_A
25700 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 PI SQLITE_DEPREC
25710 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 ATED void sqlite
25720 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 3_thread_cleanup
25730 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 (void);.SQLITE_A
25740 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 PI SQLITE_DEPREC
25750 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 ATED int sqlite3
25760 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f _memory_alarm(vo
25770 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 id(*)(void*,sqli
25780 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 te3_int64,int),v
25790 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 oid*,sqlite3_int
257a0 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 64);.#endif../*.
257b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 ** CAPI3REF: Obt
257c0 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 aining SQL Funct
257d0 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 ion Parameter Va
257e0 6c 75 65 73 20 7b 48 31 35 31 30 30 7d 20 3c 53 lues {H15100} <S
257f0 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20200>.**.** The
25800 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c C-language impl
25810 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 ementation of SQ
25820 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 L functions and
25830 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a aggregates uses.
25840 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 ** this set of i
25850 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 nterface routine
25860 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 s to access the
25870 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 parameter values
25880 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 on.** the funct
25890 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 ion or aggregate
258a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e ..**.** The xFun
258b0 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 c (for scalar fu
258c0 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 nctions) or xSte
258d0 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 p (for aggregate
258e0 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a s) parameters.**
258f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 to [sqlite3_cre
25900 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 ate_function()]
25910 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 and [sqlite3_cre
25920 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 ate_function16()
25930 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c ].** define call
25940 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 backs that imple
25950 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e ment the SQL fun
25960 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 ctions and aggre
25970 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 gates..** The 4t
25980 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
25990 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 hese callbacks i
259a0 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f s an array of po
259b0 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 inters to.** [pr
259c0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
259d0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 value] objects.
259e0 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 There is one [s
259f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
25a00 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 ject for.** each
25a10 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
25a20 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 e SQL function.
25a30 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
25a40 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 are used to.** e
25a50 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 xtract values fr
25a60 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f om the [sqlite3_
25a70 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a value] objects..
25a80 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
25a90 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 ines work only w
25aa0 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 ith [protected s
25ab0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
25ac0 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 jects..** Any at
25ad0 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 tempt to use the
25ae0 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 se routines on a
25af0 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 n [unprotected s
25b00 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a qlite3_value].**
25b10 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 object results
25b20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 in undefined beh
25b30 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 avior..**.** The
25b40 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b se routines work
25b50 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 just like the c
25b60 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f orresponding [co
25b70 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 lumn access func
25b80 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 tions].** except
25b90 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 that these rou
25ba0 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e tines take a sin
25bb0 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 gle [protected s
25bc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
25bd0 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 ject.** pointer
25be0 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 instead of a [sq
25bf0 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 lite3_stmt*] poi
25c00 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 nter and an inte
25c10 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 ger column numbe
25c20 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c r..**.** The sql
25c30 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
25c40 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 6() interface ex
25c50 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 tracts a UTF-16
25c60 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 string.** in the
25c70 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 native byte-ord
25c80 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d er of the host m
25c90 61 63 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 achine. The.**
25ca0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
25cb0 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c xt16be() and sql
25cc0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
25cd0 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 6le() interfaces
25ce0 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d .** extract UTF-
25cf0 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 16 strings as bi
25d00 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 g-endian and lit
25d10 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 tle-endian respe
25d20 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 ctively..**.** T
25d30 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 he sqlite3_value
25d40 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 _numeric_type()
25d50 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 interface attemp
25d60 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e ts to apply.** n
25d70 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 umeric affinity
25d80 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 to the value. T
25d90 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 his means that a
25da0 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 n attempt is.**
25db0 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 made to convert
25dc0 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 the value to an
25dd0 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 integer or float
25de0 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a ing point. If.*
25df0 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 * such a convers
25e00 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 ion is possible
25e10 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 without loss of
25e20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 information (in
25e30 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 other.** words,
25e40 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 if the value is
25e50 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f a string that lo
25e60 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 oks like a numbe
25e70 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 r).** then the c
25e80 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 onversion is per
25e90 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 formed. Otherwi
25ea0 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e se no conversion
25eb0 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 occurs..** The
25ec0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 [SQLITE_INTEGER
25ed0 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 | datatype] afte
25ee0 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 r conversion is
25ef0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
25f00 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69 Please pay parti
25f10 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 cular attention
25f20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74 to the fact that
25f30 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 the pointer ret
25f40 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 urned.** from [s
25f50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f qlite3_value_blo
25f60 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 b()], [sqlite3_v
25f70 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 alue_text()], or
25f80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c .** [sqlite3_val
25f90 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e ue_text16()] can
25fa0 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 be invalidated
25fb0 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 by a subsequent
25fc0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 call to.** [sqli
25fd0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 te3_value_bytes(
25fe0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c )], [sqlite3_val
25ff0 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b ue_bytes16()], [
26000 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
26010 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 xt()],.** or [sq
26020 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
26030 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 16()]..**.** The
26040 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 se routines must
26050 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 be called from
26060 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 the same thread
26070 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 as.** the SQL fu
26080 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 nction that supp
26090 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 lied the [sqlite
260a0 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 3_value*] parame
260b0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 ters..**.** Requ
260c0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
260d0 35 31 30 33 5d 20 5b 48 31 35 31 30 36 5d 20 5b 5103] [H15106] [
260e0 48 31 35 31 30 39 5d 20 5b 48 31 35 31 31 32 5d H15109] [H15112]
260f0 20 5b 48 31 35 31 31 35 5d 20 5b 48 31 35 31 31 [H15115] [H1511
26100 38 5d 20 5b 48 31 35 31 32 31 5d 20 5b 48 31 35 8] [H15121] [H15
26110 31 32 34 5d 0a 2a 2a 20 5b 48 31 35 31 32 37 5d 124].** [H15127]
26120 20 5b 48 31 35 31 33 30 5d 20 5b 48 31 35 31 33 [H15130] [H1513
26130 33 5d 20 5b 48 31 35 31 33 36 5d 0a 2a 2f 0a 53 3] [H15136].*/.S
26140 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
26150 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 void *sqlite3_va
26160 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 lue_blob(sqlite3
26170 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 _value*);.SQLITE
26180 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
26190 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c _value_bytes(sql
261a0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 ite3_value*);.SQ
261b0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
261c0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 ite3_value_bytes
261d0 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 16(sqlite3_value
261e0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 *);.SQLITE_API d
261f0 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 ouble sqlite3_va
26200 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 lue_double(sqlit
26210 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 e3_value*);.SQLI
26220 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
26230 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c e3_value_int(sql
26240 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 ite3_value*);.SQ
26250 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 LITE_API sqlite3
26260 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 _int64 sqlite3_v
26270 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 alue_int64(sqlit
26280 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 e3_value*);.SQLI
26290 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 TE_API const uns
262a0 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 igned char *sqli
262b0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 te3_value_text(s
262c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
262d0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
262e0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 void *sqlite3_v
262f0 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 alue_text16(sqli
26300 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c te3_value*);.SQL
26310 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f ITE_API const vo
26320 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 id *sqlite3_valu
26330 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 e_text16le(sqlit
26340 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 e3_value*);.SQLI
26350 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 TE_API const voi
26360 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 d *sqlite3_value
26370 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 _text16be(sqlite
26380 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 3_value*);.SQLIT
26390 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
263a0 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 3_value_type(sql
263b0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 ite3_value*);.SQ
263c0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
263d0 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 ite3_value_numer
263e0 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f ic_type(sqlite3_
263f0 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 value*);../*.**
26400 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e CAPI3REF: Obtain
26410 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 Aggregate Funct
26420 69 6f 6e 20 43 6f 6e 74 65 78 74 20 7b 48 31 36 ion Context {H16
26430 32 31 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 210} <S20200>.**
26440 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e .** The implemen
26450 74 61 74 69 6f 6e 20 6f 66 20 61 67 67 72 65 67 tation of aggreg
26460 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ate SQL function
26470 73 20 75 73 65 20 74 68 69 73 20 72 6f 75 74 69 s use this routi
26480 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a ne to allocate.*
26490 2a 20 61 20 73 74 72 75 63 74 75 72 65 20 66 6f * a structure fo
264a0 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 r storing their
264b0 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 state..**.** The
264c0 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 first time the
264d0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
264e0 65 5f 63 6f 6e 74 65 78 74 28 29 20 72 6f 75 74 e_context() rout
264f0 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 66 6f ine is called fo
26500 72 20 61 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 r a.** particula
26510 72 20 61 67 67 72 65 67 61 74 65 2c 20 53 51 4c r aggregate, SQL
26520 69 74 65 20 61 6c 6c 6f 63 61 74 65 73 20 6e 42 ite allocates nB
26530 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 ytes of memory,
26540 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 0a zeroes out that.
26550 2a 2a 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 ** memory, and r
26560 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
26570 20 74 6f 20 69 74 2e 20 4f 6e 20 73 65 63 6f 6e to it. On secon
26580 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 d and subsequent
26590 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c calls to.** sql
265a0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
265b0 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 ontext() for the
265c0 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 same aggregate
265d0 66 75 6e 63 74 69 6f 6e 20 69 6e 64 65 78 2c 0a function index,.
265e0 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 ** the same buff
265f0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 er is returned.
26600 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 The implementati
26610 6f 6e 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 on of the aggreg
26620 61 74 65 20 63 61 6e 20 75 73 65 0a 2a 2a 20 74 ate can use.** t
26630 68 65 20 72 65 74 75 72 6e 65 64 20 62 75 66 66 he returned buff
26640 65 72 20 74 6f 20 61 63 63 75 6d 75 6c 61 74 65 er to accumulate
26650 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c data..**.** SQL
26660 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c ite automaticall
26670 79 20 66 72 65 65 73 20 74 68 65 20 61 6c 6c 6f y frees the allo
26680 63 61 74 65 64 20 62 75 66 66 65 72 20 77 68 65 cated buffer whe
26690 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a n the aggregate.
266a0 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 ** query conclud
266b0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 es..**.** The fi
266c0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 73 68 rst parameter sh
266d0 6f 75 6c 64 20 62 65 20 61 20 63 6f 70 79 20 6f ould be a copy o
266e0 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 f the.** [sqlite
266f0 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 3_context | SQL
26700 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 function context
26710 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69 ] that is the fi
26720 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a rst parameter.**
26730 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
26740 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d routine that im
26750 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 plements the agg
26760 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2e regate function.
26770 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
26780 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c ine must be call
26790 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 ed from the same
267a0 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 thread in which
267b0 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 .** the aggregat
267c0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 e SQL function i
267d0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a s running..**.**
267e0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
267f0 2a 20 5b 48 31 36 32 31 31 5d 20 5b 48 31 36 32 * [H16211] [H162
26800 31 33 5d 20 5b 48 31 36 32 31 35 5d 20 5b 48 31 13] [H16215] [H1
26810 36 32 31 37 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 6217].*/.SQLITE_
26820 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 API void *sqlite
26830 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 3_aggregate_cont
26840 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ext(sqlite3_cont
26850 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 ext*, int nBytes
26860 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
26870 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f EF: User Data Fo
26880 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 r Functions {H16
26890 32 34 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 240} <S20200>.**
268a0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
268b0 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 user_data() inte
268c0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
268d0 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 copy of.** the p
268e0 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 ointer that was
268f0 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61 the pUserData pa
26900 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 rameter (the 5th
26910 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f parameter).** o
26920 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 f the [sqlite3_c
26930 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
26940 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 ].** and [sqlite
26950 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
26960 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 n16()] routines
26970 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a that originally.
26980 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 ** registered th
26990 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 e application de
269a0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 fined function.
269b0 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 {END}.**.** This
269c0 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 routine must be
269d0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 called from the
269e0 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 same thread in
269f0 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 which.** the app
26a00 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
26a10 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e function is run
26a20 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 ning..**.** Requ
26a30 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
26a40 36 32 34 33 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 6243].*/.SQLITE_
26a50 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 API void *sqlite
26a60 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 3_user_data(sqli
26a70 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a te3_context*);..
26a80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
26a90 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 Database Connect
26aa0 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e ion For Function
26ab0 73 20 7b 48 31 36 32 35 30 7d 20 3c 53 36 30 36 s {H16250} <S606
26ac0 30 30 3e 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 00><S20200>.**.*
26ad0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f * The sqlite3_co
26ae0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 ntext_db_handle(
26af0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
26b00 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a rns a copy of.**
26b10 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 the pointer to
26b20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
26b30 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 nnection] (the 1
26b40 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a st parameter).**
26b50 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
26b60 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
26b70 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 ()].** and [sqli
26b80 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
26b90 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 ion16()] routine
26ba0 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c s that originall
26bb0 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 y.** registered
26bc0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
26bd0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
26be0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
26bf0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 32 35 33 ents:.** [H16253
26c00 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
26c10 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 sqlite3 *sqlite3
26c20 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 _context_db_hand
26c30 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 le(sqlite3_conte
26c40 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 xt*);../*.** CAP
26c50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 I3REF: Function
26c60 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 20 7b Auxiliary Data {
26c70 48 31 36 32 37 30 7d 20 3c 53 32 30 32 30 30 3e H16270} <S20200>
26c80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f .**.** The follo
26c90 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f wing two functio
26ca0 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 ns may be used b
26cb0 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e y scalar SQL fun
26cc0 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 ctions to.** ass
26cd0 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 ociate metadata
26ce0 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 with argument va
26cf0 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d lues. If the sam
26d00 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 e value is passe
26d10 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 d to.** multiple
26d20 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 invocations of
26d30 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e the same SQL fun
26d40 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 ction during que
26d50 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e ry execution, un
26d60 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 der.** some circ
26d70 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 umstances the as
26d80 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 sociated metadat
26d90 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 a may be preserv
26da0 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 ed. This may.**
26db0 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 be used, for exa
26dc0 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 mple, to add a r
26dd0 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f egular-expressio
26de0 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 n matching scala
26df0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 r.** function. T
26e00 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 he compiled vers
26e10 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c ion of the regul
26e20 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 ar expression is
26e30 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 stored as.** me
26e40 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 tadata associate
26e50 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 d with the SQL v
26e60 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 alue passed as t
26e70 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 he regular expre
26e80 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e ssion.** pattern
26e90 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 . The compiled
26ea0 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 regular expressi
26eb0 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 on can be reused
26ec0 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 on multiple.**
26ed0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 invocations of t
26ee0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e he same function
26ef0 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 so that the ori
26f00 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 ginal pattern st
26f10 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 ring.** does not
26f20 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f need to be reco
26f30 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 mpiled on each i
26f40 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a nvocation..**.**
26f50 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 The sqlite3_get
26f60 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 _auxdata() inter
26f70 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 face returns a p
26f80 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 ointer to the me
26f90 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 tadata.** associ
26fa0 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 ated by the sqli
26fb0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 te3_set_auxdata(
26fc0 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 ) function with
26fd0 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 the Nth argument
26fe0 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 .** value to the
26ff0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
27000 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 49 ined function. I
27010 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 f no metadata ha
27020 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 s been ever.** b
27030 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 een set for the
27040 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 Nth argument of
27050 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 the function, or
27060 20 69 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f if the correspo
27070 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f nding.** functio
27080 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 n parameter has
27090 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 changed since th
270a0 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 e meta-data was
270b0 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c set,.** then sql
270c0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 ite3_get_auxdata
270d0 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c () returns a NUL
270e0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a L pointer..**.**
270f0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 The sqlite3_set
27100 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 _auxdata() inter
27110 66 61 63 65 20 73 61 76 65 73 20 74 68 65 20 6d face saves the m
27120 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 etadata.** point
27130 65 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 ed to by its 3rd
27140 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 parameter as th
27150 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 e metadata for t
27160 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d he N-th.** argum
27170 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 ent of the appli
27180 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
27190 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 unction. Subseq
271a0 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f uent.** calls to
271b0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 sqlite3_get_aux
271c0 64 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 data() might ret
271d0 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 urn this data, i
271e0 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 f it has.** not
271f0 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a been destroyed..
27200 2a 2a 20 49 66 20 69 74 20 69 73 20 6e 6f 74 20 ** If it is not
27210 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c NULL, SQLite wil
27220 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 l invoke the des
27230 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 tructor.** funct
27240 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 ion given by the
27250 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 4th parameter t
27260 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 o sqlite3_set_au
27270 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 xdata() on.** th
27280 65 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 e metadata when
27290 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e the correspondin
272a0 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d g function param
272b0 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 eter changes.**
272c0 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 or when the SQL
272d0 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 statement comple
272e0 74 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 tes, whichever c
272f0 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a omes first..**.*
27300 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 * SQLite is free
27310 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 to call the des
27320 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 tructor and drop
27330 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 metadata on any
27340 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 .** parameter of
27350 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 any function at
27360 20 61 6e 79 20 74 69 6d 65 2e 20 20 54 68 65 20 any time. The
27370 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 only guarantee i
27380 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 s that.** the de
27390 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 structor will be
273a0 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 called before t
273b0 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 he metadata is d
273c0 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e ropped..**.** In
273d0 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 practice, metad
273e0 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64 ata is preserved
273f0 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f between functio
27400 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 n calls for.** e
27410 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 xpressions that
27420 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 are constant at
27430 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 compile time. Th
27440 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 is includes lite
27450 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e ral.** values an
27460 64 20 53 51 4c 20 76 61 72 69 61 62 6c 65 73 2e d SQL variables.
27470 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
27480 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 tines must be ca
27490 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 lled from the sa
274a0 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 me thread in whi
274b0 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 ch.** the SQL fu
274c0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e nction is runnin
274d0 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 g..**.** Require
274e0 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 32 37 ments:.** [H1627
274f0 32 5d 20 5b 48 31 36 32 37 34 5d 20 5b 48 31 36 2] [H16274] [H16
27500 32 37 36 5d 20 5b 48 31 36 32 37 37 5d 20 5b 48 276] [H16277] [H
27510 31 36 32 37 38 5d 20 5b 48 31 36 32 37 39 5d 0a 16278] [H16279].
27520 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f */.SQLITE_API vo
27530 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f id *sqlite3_get_
27540 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f auxdata(sqlite3_
27550 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 context*, int N)
27560 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 ;.SQLITE_API voi
27570 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 d sqlite3_set_au
27580 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f xdata(sqlite3_co
27590 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 ntext*, int N, v
275a0 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 oid*, void (*)(v
275b0 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 oid*));.../*.**
275c0 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 CAPI3REF: Consta
275d0 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 nts Defining Spe
275e0 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 cial Destructor
275f0 42 65 68 61 76 69 6f 72 20 7b 48 31 30 32 38 30 Behavior {H10280
27600 7d 20 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a } <S30100>.**.**
27610 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 These are speci
27620 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 al values for th
27630 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 e destructor tha
27640 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 t is passed in a
27650 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 s the.** final a
27660 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 rgument to routi
27670 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 nes like [sqlite
27680 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 3_result_blob()]
27690 2e 20 20 49 66 20 74 68 65 20 64 65 73 74 72 75 . If the destru
276a0 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 ctor.** argument
276b0 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 is SQLITE_STATI
276c0 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 C, it means that
276d0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 the content poi
276e0 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 nter is constant
276f0 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 .** and will nev
27700 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 er change. It d
27710 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 oes not need to
27720 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 54 be destroyed. T
27730 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 he.** SQLITE_TRA
27740 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 NSIENT value mea
27750 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 ns that the cont
27760 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 ent will likely
27770 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 change in.** the
27780 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 near future and
27790 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f that SQLite sho
277a0 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e uld make its own
277b0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 private copy of
277c0 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 .** the content
277d0 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 before returning
277e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 ..**.** The type
277f0 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 def is necessary
27800 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 to work around
27810 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 problems in cert
27820 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 ain.** C++ compi
27830 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 lers. See ticke
27840 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 t #2191..*/.type
27850 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 def void (*sqlit
27860 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 e3_destructor_ty
27870 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 pe)(void*);.#def
27880 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 ine SQLITE_STATI
27890 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 C ((sqlite3
278a0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 _destructor_type
278b0 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 )0).#define SQLI
278c0 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 TE_TRANSIENT (
278d0 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 (sqlite3_destruc
278e0 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a tor_type)-1)../*
278f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 .** CAPI3REF: Se
27900 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 tting The Result
27910 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 Of An SQL Funct
27920 69 6f 6e 20 7b 48 31 36 34 30 30 7d 20 3c 53 32 ion {H16400} <S2
27930 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 0200>.**.** Thes
27940 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 e routines are u
27950 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 sed by the xFunc
27960 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 or xFinal callb
27970 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 acks that.** imp
27980 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 lement SQL funct
27990 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 ions and aggrega
279a0 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 tes. See.** [sq
279b0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
279c0 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 ction()] and [sq
279d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
279e0 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f ction16()].** fo
279f0 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 r additional inf
27a00 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 ormation..**.**
27a10 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 These functions
27a20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c work very much l
27a30 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 ike the [paramet
27a40 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 er binding] fami
27a50 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f ly of.** functio
27a60 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 ns used to bind
27a70 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 values to host p
27a80 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 arameters in pre
27a90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 pared statements
27aa0 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 ..** Refer to th
27ab0 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 e [SQL parameter
27ac0 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 ] documentation
27ad0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 for additional i
27ae0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a nformation..**.*
27af0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 * The sqlite3_re
27b00 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 sult_blob() inte
27b10 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 rface sets the r
27b20 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e esult from.** an
27b30 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
27b40 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f ined function to
27b50 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f be the BLOB who
27b60 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f se content is po
27b70 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 inted.** to by t
27b80 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
27b90 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 ter and which is
27ba0 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 N bytes long wh
27bb0 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 ere N is the.**
27bc0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e third parameter.
27bd0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
27be0 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c e3_result_zerobl
27bf0 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 ob() interfaces
27c00 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f set the result o
27c10 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 f.** the applica
27c20 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
27c30 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c ction to be a BL
27c40 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c OB containing al
27c50 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 l zero.** bytes
27c60 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 and N bytes in s
27c70 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 ize, where N is
27c80 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 the value of the
27c90 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2nd parameter..
27ca0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
27cb0 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 3_result_double(
27cc0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 ) interface sets
27cd0 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d the result from
27ce0 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 .** an applicati
27cf0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
27d00 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 ion to be a floa
27d10 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 ting point value
27d20 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 specified.** by
27d30 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e its 2nd argumen
27d40 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c t..**.** The sql
27d50 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
27d60 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f r() and sqlite3_
27d70 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 result_error16()
27d80 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 functions.** ca
27d90 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e use the implemen
27da0 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ted SQL function
27db0 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 to throw an exc
27dc0 65 70 74 69 6f 6e 2e 0a 2a 2a 20 53 51 4c 69 74 eption..** SQLit
27dd0 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e e uses the strin
27de0 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 g pointed to by
27df0 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d the.** 2nd param
27e00 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f eter of sqlite3_
27e10 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f result_error() o
27e20 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 r sqlite3_result
27e30 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 _error16().** as
27e40 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 the text of an
27e50 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 error message.
27e60 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 SQLite interpret
27e70 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d s the error.** m
27e80 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 essage string fr
27e90 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c om sqlite3_resul
27ea0 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 t_error() as UTF
27eb0 2d 38 2e 20 53 51 4c 69 74 65 0a 2a 2a 20 69 6e -8. SQLite.** in
27ec0 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72 terprets the str
27ed0 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 ing from sqlite3
27ee0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
27ef0 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e ) as UTF-16 in n
27f00 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 ative.** byte or
27f10 64 65 72 2e 20 20 49 66 20 74 68 65 20 74 68 69 der. If the thi
27f20 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
27f30 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
27f40 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c rror().** or sql
27f50 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
27f60 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 r16() is negativ
27f70 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 e then SQLite ta
27f80 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 kes as the error
27f90 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 .** message all
27fa0 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 text up through
27fb0 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 the first zero c
27fc0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 haracter..** If
27fd0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
27fe0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 ter to sqlite3_r
27ff0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 esult_error() or
28000 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 .** sqlite3_resu
28010 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 lt_error16() is
28020 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 non-negative the
28030 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 n SQLite takes t
28040 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 hat many.** byte
28050 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 s (not character
28060 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 s) from the 2nd
28070 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 parameter as the
28080 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a error message..
28090 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 ** The sqlite3_r
280a0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e esult_error() an
280b0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
280c0 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f _error16().** ro
280d0 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 utines make a pr
280e0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 ivate copy of th
280f0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 e error message
28100 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 text before.** t
28110 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e hey return. Hen
28120 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 ce, the calling
28130 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 function can dea
28140 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f llocate or.** mo
28150 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66 dify the text af
28160 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 ter they return
28170 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a without harm..**
28180 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 The sqlite3_res
28190 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 ult_error_code()
281a0 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 function change
281b0 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 s the error code
281c0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 .** returned by
281d0 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 SQLite as a resu
281e0 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 lt of an error i
281f0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 42 n a function. B
28200 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 y default,.** th
28210 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 e error code is
28220 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 41 SQLITE_ERROR. A
28230 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c subsequent call
28240 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 to sqlite3_resu
28250 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 lt_error().** or
28260 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
28270 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 error16() resets
28280 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 the error code
28290 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e to SQLITE_ERROR.
282a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
282b0 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 e3_result_toobig
282c0 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 () interface cau
282d0 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 ses SQLite to th
282e0 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 row an error.**
282f0 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 indicating that
28300 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 a string or BLOB
28310 20 69 73 20 74 6f 20 6c 6f 6e 67 20 74 6f 20 72 is to long to r
28320 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 epresent..**.**
28330 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
28340 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 lt_nomem() inter
28350 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 face causes SQLi
28360 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 te to throw an e
28370 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 rror.** indicati
28380 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 ng that a memory
28390 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c allocation fail
283a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ed..**.** The sq
283b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 lite3_result_int
283c0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 () interface set
283d0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c s the return val
283e0 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 ue.** of the app
283f0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
28400 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
28410 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 the 32-bit signe
28420 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c d integer.** val
28430 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 ue given in the
28440 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 2nd argument..**
28450 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 The sqlite3_res
28460 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 ult_int64() inte
28470 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 rface sets the r
28480 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f eturn value.** o
28490 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
284a0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
284b0 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d on to be the 64-
284c0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 bit signed integ
284d0 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 er.** value give
284e0 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 n in the 2nd arg
284f0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ument..**.** The
28500 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
28510 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 null() interface
28520 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e sets the return
28530 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 value.** of the
28540 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
28550 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f ined function to
28560 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 be NULL..**.**
28570 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
28580 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 lt_text(), sqlit
28590 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 e3_result_text16
285a0 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 (),.** sqlite3_r
285b0 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 esult_text16le()
285c0 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 , and sqlite3_re
285d0 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 sult_text16be()
285e0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 interfaces.** se
285f0 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c t the return val
28600 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 ue of the applic
28610 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
28620 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 nction to be.**
28630 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 a text string wh
28640 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 ich is represent
28650 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 ed as UTF-8, UTF
28660 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 -16 native byte
28670 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 order,.** UTF-16
28680 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 little endian,
28690 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e or UTF-16 big en
286a0 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 dian, respective
286b0 6c 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 74 61 ly..** SQLite ta
286c0 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73 kes the text res
286d0 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 ult from the app
286e0 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a lication from.**
286f0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
28700 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 er of the sqlite
28710 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 3_result_text* i
28720 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 49 66 nterfaces..** If
28730 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 the 3rd paramet
28740 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 er to the sqlite
28750 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 3_result_text* i
28760 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 nterfaces.** is
28770 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 negative, then S
28780 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 QLite takes resu
28790 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 lt text from the
287a0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2nd parameter.*
287b0 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 * through the fi
287c0 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 rst zero charact
287d0 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 er..** If the 3r
287e0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 d parameter to t
287f0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
28800 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 t_text* interfac
28810 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 es.** is non-neg
28820 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d ative, then as m
28830 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 any bytes (not c
28840 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 haracters) of th
28850 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 e text.** pointe
28860 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 d to by the 2nd
28870 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 parameter are ta
28880 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 ken as the appli
28890 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a cation-defined.*
288a0 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c * function resul
288b0 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 t..** If the 4th
288c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
288d0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
288e0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 _text* interface
288f0 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f s.** or sqlite3_
28900 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 result_blob is a
28910 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 non-NULL pointe
28920 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 r, then SQLite c
28930 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e alls that.** fun
28940 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 ction as the des
28950 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 tructor on the t
28960 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 ext or BLOB resu
28970 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a lt when it has.*
28980 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 * finished using
28990 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a that result..**
289a0 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 If the 4th para
289b0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c meter to the sql
289c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
289d0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 * interfaces or
289e0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 to.** sqlite3_re
289f0 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 sult_blob is the
28a00 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e special constan
28a10 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c t SQLITE_STATIC,
28a20 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 then SQLite.**
28a30 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 assumes that the
28a40 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 text or BLOB re
28a50 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 sult is in const
28a60 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f ant space and do
28a70 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 es not.** copy t
28a80 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 he content of th
28a90 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 e parameter nor
28aa0 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f call a destructo
28ab0 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 r on the content
28ac0 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 .** when it has
28ad0 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 finished using t
28ae0 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 hat result..** I
28af0 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 f the 4th parame
28b00 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ter to the sqlit
28b10 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 e3_result_text*
28b20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 interfaces.** or
28b30 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
28b40 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 blob is the spec
28b50 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c ial constant SQL
28b60 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a ITE_TRANSIENT.**
28b70 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b then SQLite mak
28b80 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 es a copy of the
28b90 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 result into spa
28ba0 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ce obtained from
28bb0 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 .** from [sqlite
28bc0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 3_malloc()] befo
28bd0 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a re it returns..*
28be0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
28bf0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 _result_value()
28c00 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 interface sets t
28c10 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 he result of.**
28c20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
28c30 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
28c40 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 to be a copy th
28c50 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 e.** [unprotecte
28c60 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
28c70 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 object specifie
28c80 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 d by the 2nd par
28c90 61 6d 65 74 65 72 2e 20 20 54 68 65 0a 2a 2a 20 ameter. The.**
28ca0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 sqlite3_result_v
28cb0 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 alue() interface
28cc0 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 makes a copy of
28cd0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 the [sqlite3_va
28ce0 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 lue].** so that
28cf0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c the [sqlite3_val
28d00 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e ue] specified in
28d10 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d the parameter m
28d20 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 ay change or.**
28d30 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 be deallocated a
28d40 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 fter sqlite3_res
28d50 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 ult_value() retu
28d60 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d rns without harm
28d70 2e 0a 2a 2a 20 41 20 5b 70 72 6f 74 65 63 74 65 ..** A [protecte
28d80 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
28d90 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 object may alwa
28da0 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65 ys be used where
28db0 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 an.** [unprotec
28dc0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
28dd0 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 e] object is req
28de0 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 uired, so either
28df0 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c .** kind of [sql
28e00 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
28e10 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 ct can be used w
28e20 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 ith this interfa
28e30 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 ce..**.** If the
28e40 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
28e50 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 called from with
28e60 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 in the different
28e70 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 thread.** than
28e80 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 the one containi
28e90 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ng the applicati
28ea0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
28eb0 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 ion that receive
28ec0 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 d.** the [sqlite
28ed0 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 3_context] point
28ee0 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 er, the results
28ef0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a are undefined..*
28f00 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
28f10 73 3a 0a 2a 2a 20 5b 48 31 36 34 30 33 5d 20 5b s:.** [H16403] [
28f20 48 31 36 34 30 36 5d 20 5b 48 31 36 34 30 39 5d H16406] [H16409]
28f30 20 5b 48 31 36 34 31 32 5d 20 5b 48 31 36 34 31 [H16412] [H1641
28f40 35 5d 20 5b 48 31 36 34 31 38 5d 20 5b 48 31 36 5] [H16418] [H16
28f50 34 32 31 5d 20 5b 48 31 36 34 32 34 5d 0a 2a 2a 421] [H16424].**
28f60 20 5b 48 31 36 34 32 37 5d 20 5b 48 31 36 34 33 [H16427] [H1643
28f70 30 5d 20 5b 48 31 36 34 33 33 5d 20 5b 48 31 36 0] [H16433] [H16
28f80 34 33 36 5d 20 5b 48 31 36 34 33 39 5d 20 5b 48 436] [H16439] [H
28f90 31 36 34 34 32 5d 20 5b 48 31 36 34 34 35 5d 20 16442] [H16445]
28fa0 5b 48 31 36 34 34 38 5d 0a 2a 2a 20 5b 48 31 36 [H16448].** [H16
28fb0 34 35 31 5d 20 5b 48 31 36 34 35 34 5d 20 5b 48 451] [H16454] [H
28fc0 31 36 34 35 37 5d 20 5b 48 31 36 34 36 30 5d 20 16457] [H16460]
28fd0 5b 48 31 36 34 36 33 5d 0a 2a 2f 0a 53 51 4c 49 [H16463].*/.SQLI
28fe0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 TE_API void sqli
28ff0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 te3_result_blob(
29000 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
29010 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 , const void*, i
29020 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 nt, void(*)(void
29030 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 *));.SQLITE_API
29040 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
29050 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 ult_double(sqlit
29060 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 e3_context*, dou
29070 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ble);.SQLITE_API
29080 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 void sqlite3_re
29090 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 sult_error(sqlit
290a0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e e3_context*, con
290b0 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a st char*, int);.
290c0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
290d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
290e0 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 rror16(sqlite3_c
290f0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 ontext*, const v
29100 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 oid*, int);.SQLI
29110 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 TE_API void sqli
29120 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
29130 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f _toobig(sqlite3_
29140 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 context*);.SQLIT
29150 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 E_API void sqlit
29160 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f e3_result_error_
29170 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f nomem(sqlite3_co
29180 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f ntext*);.SQLITE_
29190 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 API void sqlite3
291a0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f _result_error_co
291b0 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 de(sqlite3_conte
291c0 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 xt*, int);.SQLIT
291d0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 E_API void sqlit
291e0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 e3_result_int(sq
291f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
29200 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 int);.SQLITE_API
29210 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 void sqlite3_re
29220 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 sult_int64(sqlit
29230 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c e3_context*, sql
29240 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c ite3_int64);.SQL
29250 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c ITE_API void sql
29260 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c ite3_result_null
29270 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
29280 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 *);.SQLITE_API v
29290 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
292a0 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f lt_text(sqlite3_
292b0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
292c0 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 char*, int, void
292d0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c (*)(void*));.SQL
292e0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c ITE_API void sql
292f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
29300 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 16(sqlite3_conte
29310 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a xt*, const void*
29320 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 , int, void(*)(v
29330 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 oid*));.SQLITE_A
29340 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f PI void sqlite3_
29350 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 result_text16le(
29360 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
29370 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 , const void*, i
29380 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a nt,void(*)(void*
29390 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 ));.SQLITE_API v
293a0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
293b0 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 lt_text16be(sqli
293c0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f te3_context*, co
293d0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 nst void*, int,v
293e0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
293f0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
29400 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 sqlite3_result_v
29410 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e alue(sqlite3_con
29420 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 text*, sqlite3_v
29430 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 alue*);.SQLITE_A
29440 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f PI void sqlite3_
29450 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 result_zeroblob(
29460 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
29470 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a , int n);../*.**
29480 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e CAPI3REF: Defin
29490 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 e New Collating
294a0 53 65 71 75 65 6e 63 65 73 20 7b 48 31 36 36 30 Sequences {H1660
294b0 30 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 0} <S20300>.**.*
294c0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e * These function
294d0 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 s are used to ad
294e0 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 d new collation
294f0 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74 68 65 sequences to the
29500 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
29510 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 nnection] specif
29520 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 ied as the first
29530 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a argument..**.**
29540 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 The name of the
29550 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 new collation s
29560 65 71 75 65 6e 63 65 20 69 73 20 73 70 65 63 69 equence is speci
29570 66 69 65 64 20 61 73 20 61 20 55 54 46 2d 38 20 fied as a UTF-8
29580 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 string.** for sq
29590 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
295a0 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c lation() and sql
295b0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
295c0 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e ation_v2().** an
295d0 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e d a UTF-16 strin
295e0 67 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 g for sqlite3_cr
295f0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 eate_collation16
29600 28 29 2e 20 49 6e 20 61 6c 6c 20 63 61 73 65 73 (). In all cases
29610 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20 .** the name is
29620 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 passed as the se
29630 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 cond function ar
29640 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 gument..**.** Th
29650 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 e third argument
29660 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 74 may be one of t
29670 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 he constants [SQ
29680 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b LITE_UTF8],.** [
29690 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c SQLITE_UTF16LE],
296a0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 or [SQLITE_UTF1
296b0 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 6BE], indicating
296c0 20 74 68 61 74 20 74 68 65 20 75 73 65 72 2d 73 that the user-s
296d0 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69 upplied.** routi
296e0 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20 62 65 ne expects to be
296f0 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72 73 passed pointers
29700 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 6f to strings enco
29710 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 2c ded using UTF-8,
29720 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c .** UTF-16 littl
29730 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 e-endian, or UTF
29740 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 2c 20 -16 big-endian,
29750 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 54 68 respectively. Th
29760 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67 75 6d e.** third argum
29770 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f 20 62 ent might also b
29780 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d e [SQLITE_UTF16]
29790 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 to indicate tha
297a0 74 20 74 68 65 20 72 6f 75 74 69 6e 65 0a 2a 2a t the routine.**
297b0 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72 expects pointer
297c0 73 20 74 6f 20 62 65 20 55 54 46 2d 31 36 20 73 s to be UTF-16 s
297d0 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 6e 61 trings in the na
297e0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c tive byte order,
297f0 20 6f 72 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d or the.** argum
29800 65 6e 74 20 63 61 6e 20 62 65 20 5b 53 51 4c 49 ent can be [SQLI
29810 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 TE_UTF16_ALIGNED
29820 5d 20 69 66 20 74 68 65 0a 2a 2a 20 74 68 65 20 ] if the.** the
29830 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 routine expects
29840 70 6f 69 6e 74 65 72 73 20 74 6f 20 31 36 2d 62 pointers to 16-b
29850 69 74 20 77 6f 72 64 20 61 6c 69 67 6e 65 64 20 it word aligned
29860 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 strings.** of UT
29870 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 F-16 in the nati
29880 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a ve byte order..*
29890 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 *.** A pointer t
298a0 6f 20 74 68 65 20 75 73 65 72 20 73 75 70 70 6c o the user suppl
298b0 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 ied routine must
298c0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 be passed as th
298d0 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d e fifth.** argum
298e0 65 6e 74 2e 20 20 49 66 20 69 74 20 69 73 20 4e ent. If it is N
298f0 55 4c 4c 2c 20 74 68 69 73 20 69 73 20 74 68 65 ULL, this is the
29900 20 73 61 6d 65 20 61 73 20 64 65 6c 65 74 69 6e same as deletin
29910 67 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a g the collation.
29920 2a 2a 20 73 65 71 75 65 6e 63 65 20 28 73 6f 20 ** sequence (so
29930 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 6e that SQLite cann
29940 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f ot call it anymo
29950 72 65 29 2e 0a 2a 2a 20 45 61 63 68 20 74 69 6d re)..** Each tim
29960 65 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f e the applicatio
29970 6e 20 73 75 70 70 6c 69 65 64 20 66 75 6e 63 74 n supplied funct
29980 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 ion is invoked,
29990 69 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 it is passed.**
299a0 61 73 20 69 74 73 20 66 69 72 73 74 20 70 61 72 as its first par
299b0 61 6d 65 74 65 72 20 61 20 63 6f 70 79 20 6f 66 ameter a copy of
299c0 20 74 68 65 20 76 6f 69 64 2a 20 70 61 73 73 65 the void* passe
299d0 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 d as the fourth
299e0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 argument.** to s
299f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
29a00 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c llation() or sql
29a10 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
29a20 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a ation16()..**.**
29a30 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 61 The remaining a
29a40 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 rguments to the
29a50 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 application-supp
29a60 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 61 72 65 lied routine are
29a70 20 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a two strings,.**
29a80 20 65 61 63 68 20 72 65 70 72 65 73 65 6e 74 65 each represente
29a90 64 20 62 79 20 61 20 28 6c 65 6e 67 74 68 2c 20 d by a (length,
29aa0 64 61 74 61 29 20 70 61 69 72 20 61 6e 64 20 65 data) pair and e
29ab0 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 20 65 6e ncoded in the en
29ac0 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 coding.** that w
29ad0 61 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 as passed as the
29ae0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 third argument
29af0 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 when the collati
29b00 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 61 73 0a on sequence was.
29b10 2a 2a 20 72 65 67 69 73 74 65 72 65 64 2e 20 7b ** registered. {
29b20 45 4e 44 7d 20 20 54 68 65 20 61 70 70 6c 69 63 END} The applic
29b30 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f ation defined co
29b40 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20 llation routine
29b50 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e should.** return
29b60 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 negative, zero
29b70 6f 72 20 70 6f 73 69 74 69 76 65 20 69 66 20 74 or positive if t
29b80 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 he first string
29b90 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 0a 2a 2a is less than,.**
29ba0 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 equal to, or gr
29bb0 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 eater than the s
29bc0 65 63 6f 6e 64 20 73 74 72 69 6e 67 2e 20 69 2e econd string. i.
29bd0 65 2e 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54 e. (STRING1 - ST
29be0 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 RING2)..**.** Th
29bf0 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 e sqlite3_create
29c00 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 _collation_v2()
29c10 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 works like sqlit
29c20 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
29c30 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 ion().** except
29c40 74 68 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e that it takes an
29c50 20 65 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20 extra argument
29c60 77 68 69 63 68 20 69 73 20 61 20 64 65 73 74 72 which is a destr
29c70 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 uctor for.** the
29c80 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65 collation. The
29c90 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 destructor is c
29ca0 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 63 alled when the c
29cb0 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 ollation is.** d
29cc0 65 73 74 72 6f 79 65 64 20 61 6e 64 20 69 73 20 estroyed and is
29cd0 70 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66 passed a copy of
29ce0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
29cf0 6d 65 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e meter void* poin
29d00 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 ter.** of the sq
29d10 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
29d20 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 lation_v2()..**
29d30 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 64 Collations are d
29d40 65 73 74 72 6f 79 65 64 20 77 68 65 6e 20 74 68 estroyed when th
29d50 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 ey are overridde
29d60 6e 20 62 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 n by later calls
29d70 20 74 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61 to the.** colla
29d80 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 tion creation fu
29d90 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 nctions or when
29da0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
29db0 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f nnection] is clo
29dc0 73 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 sed.** using [sq
29dd0 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a lite3_close()]..
29de0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
29df0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 [sqlite3_collat
29e00 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e ion_needed()] an
29e10 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 d [sqlite3_colla
29e20 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d tion_needed16()]
29e30 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
29e40 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 36 30 33 ents:.** [H16603
29e50 5d 20 5b 48 31 36 36 30 34 5d 20 5b 48 31 36 36 ] [H16604] [H166
29e60 30 36 5d 20 5b 48 31 36 36 30 39 5d 20 5b 48 31 06] [H16609] [H1
29e70 36 36 31 32 5d 20 5b 48 31 36 36 31 35 5d 20 5b 6612] [H16615] [
29e80 48 31 36 36 31 38 5d 20 5b 48 31 36 36 32 31 5d H16618] [H16621]
29e90 0a 2a 2a 20 5b 48 31 36 36 32 34 5d 20 5b 48 31 .** [H16624] [H1
29ea0 36 36 32 37 5d 20 5b 48 31 36 36 33 30 5d 0a 2a 6627] [H16630].*
29eb0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
29ec0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
29ed0 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c collation(. sql
29ee0 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 ite3*, . const
29ef0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 char *zName, .
29f00 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 int eTextRep, .
29f10 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 void*,. int(*x
29f20 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 Compare)(void*,i
29f30 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 nt,const void*,i
29f40 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a nt,const void*).
29f50 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
29f60 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 t sqlite3_create
29f70 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 _collation_v2(.
29f80 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f sqlite3*, . co
29f90 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
29fa0 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 . int eTextRep
29fb0 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e , . void*,. in
29fc0 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 t(*xCompare)(voi
29fd0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 d*,int,const voi
29fe0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 d*,int,const voi
29ff0 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 d*),. void(*xDe
2a000 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b stroy)(void*).);
2a010 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
2a020 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
2a030 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 ollation16(. sq
2a040 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 lite3*, . const
2a050 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 void *zName,.
2a060 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 int eTextRep, .
2a070 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 void*,. int(*x
2a080 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 Compare)(void*,i
2a090 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 nt,const void*,i
2a0a0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a nt,const void*).
2a0b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2a0c0 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 EF: Collation Ne
2a0d0 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 20 7b eded Callbacks {
2a0e0 48 31 36 37 30 30 7d 20 3c 53 32 30 33 30 30 3e H16700} <S20300>
2a0f0 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 .**.** To avoid
2a100 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 having to regist
2a110 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e er all collation
2a120 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 sequences befor
2a130 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 e a database.**
2a140 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 can be used, a s
2a150 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 ingle callback f
2a160 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 unction may be r
2a170 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74 egistered with t
2a180 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 he.** [database
2a190 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 connection] to b
2a1a0 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 76 65 e called wheneve
2a1b0 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 r an undefined c
2a1c0 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 ollation.** sequ
2a1d0 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64 ence is required
2a1e0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 ..**.** If the f
2a1f0 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 unction is regis
2a200 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 tered using the
2a210 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f sqlite3_collatio
2a220 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a n_needed() API,.
2a230 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 ** then it is pa
2a240 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f ssed the names o
2a250 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c f undefined coll
2a260 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 ation sequences
2a270 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e as strings.** en
2a280 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 coded in UTF-8.
2a290 7b 48 31 36 37 30 33 7d 20 49 66 20 73 71 6c 69 {H16703} If sqli
2a2a0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 te3_collation_ne
2a2b0 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64 eded16() is used
2a2c0 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 ,.** the names a
2a2d0 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46 re passed as UTF
2a2e0 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e -16 in machine n
2a2f0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
2a300 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 65 ..** A call to e
2a310 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 ither function r
2a320 65 70 6c 61 63 65 73 20 61 6e 79 20 65 78 69 73 eplaces any exis
2a330 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a ting callback..*
2a340 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 *.** When the ca
2a350 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
2a360 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67 d, the first arg
2a370 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 ument passed is
2a380 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 a copy.** of the
2a390 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
2a3a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c to sqlite3_coll
2a3b0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f ation_needed() o
2a3c0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c r.** sqlite3_col
2a3d0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 lation_needed16(
2a3e0 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 ). The second a
2a3f0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 rgument is the d
2a400 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 atabase.** conne
2a410 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 ction. The thir
2a420 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e d argument is on
2a430 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 e of [SQLITE_UTF
2a440 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 8], [SQLITE_UTF1
2a450 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 6BE],.** or [SQL
2a460 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e ITE_UTF16LE], in
2a470 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 dicating the mos
2a480 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d t desirable form
2a490 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f of the collatio
2a4a0 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75 n.** sequence fu
2a4b0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e nction required.
2a4c0 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 The fourth par
2a4d0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 ameter is the na
2a4e0 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 me of the.** req
2a4f0 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 uired collation
2a500 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 sequence..**.**
2a510 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e The callback fun
2a520 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 ction should reg
2a530 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65 ister the desire
2a540 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e d collation usin
2a550 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 g.** [sqlite3_cr
2a560 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 eate_collation()
2a570 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 ], [sqlite3_crea
2a580 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 te_collation16()
2a590 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 ], or.** [sqlite
2a5a0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
2a5b0 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 on_v2()]..**.**
2a5c0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a Requirements:.**
2a5d0 20 5b 48 31 36 37 30 32 5d 20 5b 48 31 36 37 30 [H16702] [H1670
2a5e0 34 5d 20 5b 48 31 36 37 30 36 5d 0a 2a 2f 0a 53 4] [H16706].*/.S
2a5f0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
2a600 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
2a610 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 needed(. sqlite
2a620 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 3*, . void*, .
2a630 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 void(*)(void*,s
2a640 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 qlite3*,int eTex
2a650 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a tRep,const char*
2a660 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 ).);.SQLITE_API
2a670 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c int sqlite3_coll
2a680 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a ation_needed16(.
2a690 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 sqlite3*, . v
2a6a0 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 oid*,. void(*)(
2a6b0 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 void*,sqlite3*,i
2a6c0 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 nt eTextRep,cons
2a6d0 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a t void*).);../*.
2a6e0 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 6b ** Specify the k
2a6f0 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 ey for an encryp
2a700 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 ted database. T
2a710 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 his routine shou
2a720 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 ld be.** called
2a730 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 right after sqli
2a740 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a te3_open()..**.*
2a750 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d * The code to im
2a760 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 plement this API
2a770 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c is not availabl
2a780 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 e in the public
2a790 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 release.** of SQ
2a7a0 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f Lite..*/.SQLITE_
2a7b0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
2a7c0 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a key(. sqlite3 *
2a7d0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 db,
2a7e0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 /* Databas
2a7f0 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 e to be rekeyed
2a800 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
2a810 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 *pKey, int nKey
2a820 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a /* The key *
2a830 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e /.);../*.** Chan
2a840 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e ge the key on an
2a850 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 open database.
2a860 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 If the current
2a870 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a database is not.
2a880 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 ** encrypted, th
2a890 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 is routine will
2a8a0 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 encrypt it. If
2a8b0 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d pNew==0 or nNew=
2a8c0 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 =0, the.** datab
2a8d0 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64 ase is decrypted
2a8e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 ..**.** The code
2a8f0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 to implement th
2a900 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 is API is not av
2a910 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 ailable in the p
2a920 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a ublic release.**
2a930 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 of SQLite..*/.S
2a940 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
2a950 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 lite3_rekey(. s
2a960 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
2a970 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
2a980 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 Database to be
2a990 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e rekeyed */. con
2a9a0 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 st void *pKey, i
2a9b0 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 nt nKey /* T
2a9c0 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b he new key */.);
2a9d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2a9e0 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 : Suspend Execut
2a9f0 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 ion For A Short
2aa00 54 69 6d 65 20 7b 48 31 30 35 33 30 7d 20 3c 53 Time {H10530} <S
2aa10 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 40410>.**.** The
2aa20 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 sqlite3_sleep()
2aa30 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 function causes
2aa40 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 the current thr
2aa50 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 ead to suspend e
2aa60 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 xecution.** for
2aa70 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 at least a numbe
2aa80 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 r of millisecond
2aa90 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 s specified in i
2aaa0 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a ts parameter..**
2aab0 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 .** If the opera
2aac0 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 ting system does
2aad0 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 not support sle
2aae0 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68 ep requests with
2aaf0 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 .** millisecond
2ab00 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c time resolution,
2ab10 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 then the time w
2ab20 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 ill be rounded u
2ab30 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 p to.** the near
2ab40 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 est second. The
2ab50 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 number of millis
2ab60 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 econds of sleep
2ab70 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 actually.** requ
2ab80 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f ested from the o
2ab90 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 perating system
2aba0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a is returned..**.
2abb0 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d ** SQLite implem
2abc0 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 ents this interf
2abd0 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 ace by calling t
2abe0 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d he xSleep().** m
2abf0 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 ethod of the def
2ac00 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 ault [sqlite3_vf
2ac10 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a s] object..**.**
2ac20 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b Requirements: [
2ac30 48 31 30 35 33 33 5d 20 5b 48 31 30 35 33 36 5d H10533] [H10536]
2ac40 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
2ac50 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 nt sqlite3_sleep
2ac60 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 (int);../*.** CA
2ac70 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 PI3REF: Name Of
2ac80 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 The Folder Holdi
2ac90 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c ng Temporary Fil
2aca0 65 73 20 7b 48 31 30 33 31 30 7d 20 3c 53 32 30 es {H10310} <S20
2acb0 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 000>.**.** If th
2acc0 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 is global variab
2acd0 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f le is made to po
2ace0 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 int to a string
2acf0 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 which is.** the
2ad00 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 name of a folder
2ad10 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f (a.k.a. directo
2ad20 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 ry), then all te
2ad30 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a mporary files.**
2ad40 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 created by SQLi
2ad50 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 te will be place
2ad60 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 d in that direct
2ad70 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20 76 61 ory. If this va
2ad80 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e riable.** is a N
2ad90 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 ULL pointer, the
2ada0 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d n SQLite perform
2adb0 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 s a search for a
2adc0 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a n appropriate.**
2add0 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 temporary file
2ade0 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a directory..**.**
2adf0 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 It is not safe
2ae00 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 to read or modif
2ae10 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 y this variable
2ae20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 in more than one
2ae30 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 .** thread at a
2ae40 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 time. It is not
2ae50 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 safe to read or
2ae60 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 modify this var
2ae70 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 iable.** if a [d
2ae80 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2ae90 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 on] is being use
2aea0 64 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 d at the same ti
2aeb0 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 me in a separate
2aec0 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 .** thread..** I
2aed0 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 t is intended th
2aee0 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 at this variable
2aef0 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 be set once.**
2af00 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 as part of proce
2af10 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f ss initializatio
2af20 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 n and before any
2af30 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
2af40 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 e.** routines ha
2af50 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 ve been called a
2af60 6e 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 nd that this var
2af70 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 iable remain unc
2af80 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 hanged.** therea
2af90 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 fter..**.** The
2afa0 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 [temp_store_dire
2afb0 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 ctory pragma] ma
2afc0 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 y modify this va
2afd0 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 riable and cause
2afe0 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 .** it to point
2aff0 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e to memory obtain
2b000 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
2b010 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 46 75 72 74 68 _malloc]. Furth
2b020 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b ermore,.** the [
2b030 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 temp_store_direc
2b040 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 tory pragma] alw
2b050 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 ays assumes that
2b060 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 any string.** t
2b070 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c hat this variabl
2b080 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 e points to is h
2b090 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 eld in memory ob
2b0a0 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 tained from .**
2b0b0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d [sqlite3_malloc]
2b0c0 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 and the pragma
2b0d0 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 may attempt to f
2b0e0 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a ree that memory.
2b0f0 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ** using [sqlite
2b100 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 3_free]..** Henc
2b110 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61 e, if this varia
2b120 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 ble is modified
2b130 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 directly, either
2b140 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a it should be.**
2b150 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 made NULL or ma
2b160 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d de to point to m
2b170 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 emory obtained f
2b180 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c rom [sqlite3_mal
2b190 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 loc].** or else
2b1a0 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b the use of the [
2b1b0 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 temp_store_direc
2b1c0 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f tory pragma] sho
2b1d0 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a uld be avoided..
2b1e0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 */.SQLITE_API SQ
2b1f0 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 LITE_EXTERN char
2b200 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 *sqlite3_temp_d
2b210 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a irectory;../*.**
2b220 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 CAPI3REF: Test
2b230 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 For Auto-Commit
2b240 4d 6f 64 65 20 7b 48 31 32 39 33 30 7d 20 3c 53 Mode {H12930} <S
2b250 36 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 60200>.** KEYWOR
2b260 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 DS: {autocommit
2b270 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 mode}.**.** The
2b280 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f sqlite3_get_auto
2b290 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 commit() interfa
2b2a0 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a ce returns non-z
2b2b0 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 ero or.** zero i
2b2c0 66 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 f the given data
2b2d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
2b2e0 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 is or is not in
2b2f0 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c autocommit mode,
2b300 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 .** respectively
2b310 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f . Autocommit mo
2b320 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 de is on by defa
2b330 75 6c 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d ult..** Autocomm
2b340 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 it mode is disab
2b350 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d led by a [BEGIN]
2b360 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 41 statement..** A
2b370 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 utocommit mode i
2b380 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 s re-enabled by
2b390 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 a [COMMIT] or [R
2b3a0 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 OLLBACK]..**.**
2b3b0 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 If certain kinds
2b3c0 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 of errors occur
2b3d0 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 on a statement
2b3e0 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 within a multi-s
2b3f0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e tatement.** tran
2b400 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 saction (errors
2b410 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 including [SQLIT
2b420 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 E_FULL], [SQLITE
2b430 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c _IOERR],.** [SQL
2b440 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c ITE_NOMEM], [SQL
2b450 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b ITE_BUSY], and [
2b460 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 SQLITE_INTERRUPT
2b470 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 ]) then the.** t
2b480 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 ransaction might
2b490 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 be rolled back
2b4a0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 automatically.
2b4b0 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a The only way to.
2b4c0 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 ** find out whet
2b4d0 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d her SQLite autom
2b4e0 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 atically rolled
2b4f0 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 back the transac
2b500 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e tion after.** an
2b510 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 error is to use
2b520 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a this function..
2b530 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 **.** If another
2b540 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 thread changes
2b550 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 the autocommit s
2b560 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 tatus of the dat
2b570 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 abase.** connect
2b580 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72 ion while this r
2b590 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e outine is runnin
2b5a0 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 g, then the retu
2b5b0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 rn value.** is u
2b5c0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
2b5d0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 Requirements: [H
2b5e0 31 32 39 33 31 5d 20 5b 48 31 32 39 33 32 5d 20 12931] [H12932]
2b5f0 5b 48 31 32 39 33 33 5d 20 5b 48 31 32 39 33 34 [H12933] [H12934
2b600 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
2b610 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f int sqlite3_get_
2b620 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 autocommit(sqlit
2b630 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 e3*);../*.** CAP
2b640 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20 I3REF: Find The
2b650 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 Database Handle
2b660 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 Of A Prepared St
2b670 61 74 65 6d 65 6e 74 20 7b 48 31 33 31 32 30 7d atement {H13120}
2b680 20 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S60600>.**.**
2b690 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 The sqlite3_db_h
2b6a0 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20 andle interface
2b6b0 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74 returns the [dat
2b6c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2b6d0 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 ] handle.** to w
2b6e0 68 69 63 68 20 61 20 5b 70 72 65 70 61 72 65 64 hich a [prepared
2b6f0 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f statement] belo
2b700 6e 67 73 2e 20 20 54 68 65 20 5b 64 61 74 61 62 ngs. The [datab
2b710 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a ase connection].
2b720 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ** returned by s
2b730 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 qlite3_db_handle
2b740 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61 is the same [da
2b750 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2b760 6e 5d 20 74 68 61 74 20 77 61 73 20 74 68 65 20 n] that was the
2b770 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a first argument.*
2b780 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 * to the [sqlite
2b790 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
2b7a0 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72 call (or its var
2b7b0 69 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 20 iants) that was
2b7c0 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 used to.** creat
2b7d0 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 e the statement
2b7e0 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 in the first pla
2b7f0 63 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 ce..**.** Requir
2b800 65 6d 65 6e 74 73 3a 20 5b 48 31 33 31 32 33 5d ements: [H13123]
2b810 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 .*/.SQLITE_API s
2b820 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f qlite3 *sqlite3_
2b830 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 db_handle(sqlite
2b840 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 3_stmt*);../*.**
2b850 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 CAPI3REF: Find
2b860 74 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 65 the next prepare
2b870 64 20 73 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 d statement {H13
2b880 31 34 30 7d 20 3c 53 36 30 36 30 30 3e 0a 2a 2a 140} <S60600>.**
2b890 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 .** This interfa
2b8a0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 ce returns a poi
2b8b0 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74 nter to the next
2b8c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2b8d0 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 ment] after.** p
2b8e0 53 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20 Stmt associated
2b8f0 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 with the [databa
2b900 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 se connection] p
2b910 44 62 2e 20 20 49 66 20 70 53 74 6d 74 20 69 73 Db. If pStmt is
2b920 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 NULL.** then th
2b930 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 is interface ret
2b940 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
2b950 6f 20 74 68 65 20 66 69 72 73 74 20 70 72 65 70 o the first prep
2b960 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a ared statement.*
2b970 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 * associated wit
2b980 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 h the database c
2b990 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 onnection pDb.
2b9a0 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20 73 If no prepared s
2b9b0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 tatement.** sati
2b9c0 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69 74 sfies the condit
2b9d0 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f 75 ions of this rou
2b9e0 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e 73 tine, it returns
2b9f0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 NULL..**.** The
2ba00 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
2ba10 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44 ction] pointer D
2ba20 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a in a call to.**
2ba30 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 [sqlite3_next_s
2ba40 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20 72 tmt(D,S)] must r
2ba50 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20 efer to an open
2ba60 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
2ba70 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61 ection and in pa
2ba80 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f rticular must no
2ba90 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e t be a NULL poin
2baa0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 ter..**.** Requi
2bab0 72 65 6d 65 6e 74 73 3a 20 5b 48 31 33 31 34 33 rements: [H13143
2bac0 5d 20 5b 48 31 33 31 34 36 5d 20 5b 48 31 33 31 ] [H13146] [H131
2bad0 34 39 5d 20 5b 48 31 33 31 35 32 5d 0a 2a 2f 0a 49] [H13152].*/.
2bae0 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 SQLITE_API sqlit
2baf0 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 e3_stmt *sqlite3
2bb00 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 _next_stmt(sqlit
2bb10 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 e3 *pDb, sqlite3
2bb20 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a _stmt *pStmt);..
2bb30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2bb40 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 Commit And Rollb
2bb50 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e ack Notification
2bb60 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 Callbacks {H129
2bb70 35 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 50} <S60400>.**.
2bb80 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 ** The sqlite3_c
2bb90 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 ommit_hook() int
2bba0 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 erface registers
2bbb0 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 a callback.** f
2bbc0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e unction to be in
2bbd0 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 voked whenever a
2bbe0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 transaction is
2bbf0 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 [COMMIT | commit
2bc00 74 65 64 5d 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c ted]..** Any cal
2bc10 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 lback set by a p
2bc20 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 revious call to
2bc30 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 sqlite3_commit_h
2bc40 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 ook().** for the
2bc50 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 same database c
2bc60 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 onnection is ove
2bc70 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 rridden..** The
2bc80 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b sqlite3_rollback
2bc90 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 _hook() interfac
2bca0 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 e registers a ca
2bcb0 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 llback.** functi
2bcc0 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 on to be invoked
2bcd0 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e whenever a tran
2bce0 73 61 63 74 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c saction is [ROLL
2bcf0 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 62 61 BACK | rolled ba
2bd00 63 6b 5d 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c ck]..** Any call
2bd10 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 back set by a pr
2bd20 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 evious call to s
2bd30 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f qlite3_commit_ho
2bd40 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 ok().** for the
2bd50 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f same database co
2bd60 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 nnection is over
2bd70 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 70 ridden..** The p
2bd80 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 Arg argument is
2bd90 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 74 passed through t
2bda0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a o the callback..
2bdb0 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 ** If the callba
2bdc0 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 ck on a commit h
2bdd0 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 ook function ret
2bde0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a urns non-zero,.*
2bdf0 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 * then the commi
2be00 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 t is converted i
2be10 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a nto a rollback..
2be20 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 **.** If another
2be30 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 function was pr
2be40 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 eviously registe
2be50 72 65 64 2c 20 69 74 73 0a 2a 2a 20 70 41 72 67 red, its.** pArg
2be60 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e value is return
2be70 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 4e ed. Otherwise N
2be80 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e ULL is returned.
2be90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 .**.** The callb
2bea0 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ack implementati
2beb0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 on must not do a
2bec0 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c nything that wil
2bed0 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 l modify.** the
2bee0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2bef0 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 ion that invoked
2bf00 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 the callback.
2bf10 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 Any actions.** t
2bf20 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 o modify the dat
2bf30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2bf40 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65 must be deferre
2bf50 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 d until after th
2bf60 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 e.** completion
2bf70 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
2bf80 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 step()] call tha
2bf90 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20 t triggered the
2bfa0 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c commit.** or rol
2bfb0 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 lback hook in th
2bfc0 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a e first place..*
2bfd0 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c * Note that [sql
2bfe0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
2bff0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
2c000 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 step()] both mod
2c010 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 ify their.** dat
2c020 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2c030 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e s for the meanin
2c040 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e g of "modify" in
2c050 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e this paragraph.
2c060 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 69 .**.** Registeri
2c070 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 ng a NULL functi
2c080 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 on disables the
2c090 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 callback..**.**
2c0a0 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 When the commit
2c0b0 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f hook callback ro
2c0c0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 utine returns ze
2c0d0 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d ro, the [COMMIT]
2c0e0 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 .** operation is
2c0f0 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74 allowed to cont
2c100 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 inue normally.
2c110 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f If the commit ho
2c120 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f ok.** returns no
2c130 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 n-zero, then the
2c140 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e [COMMIT] is con
2c150 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 5b 52 verted into a [R
2c160 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 54 68 65 OLLBACK]..** The
2c170 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 rollback hook i
2c180 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72 s invoked on a r
2c190 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20 72 65 73 ollback that res
2c1a0 75 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d ults from a comm
2c1b0 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72 it.** hook retur
2c1c0 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a ning non-zero, j
2c1d0 75 73 74 20 61 73 20 69 74 20 77 6f 75 6c 64 20 ust as it would
2c1e0 62 65 20 77 69 74 68 20 61 6e 79 20 6f 74 68 65 be with any othe
2c1f0 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a r rollback..**.*
2c200 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 * For the purpos
2c210 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 es of this API,
2c220 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 a transaction is
2c230 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 said to have be
2c240 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 en.** rolled bac
2c250 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 k if an explicit
2c260 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 "ROLLBACK" stat
2c270 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 ement is execute
2c280 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f d, or.** an erro
2c290 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 r or constraint
2c2a0 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 causes an implic
2c2b0 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f it rollback to o
2c2c0 63 63 75 72 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c ccur..** The rol
2c2d0 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 lback callback i
2c2e0 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 s not invoked if
2c2f0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 a transaction i
2c300 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c s.** automatical
2c310 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 ly rolled back b
2c320 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62 ecause the datab
2c330 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ase connection i
2c340 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 54 68 65 s closed..** The
2c350 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 rollback callba
2c360 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 ck is not invoke
2c370 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 d if a transacti
2c380 6f 6e 20 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64 20 on is.** rolled
2c390 62 61 63 6b 20 62 65 63 61 75 73 65 20 61 20 63 back because a c
2c3a0 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20 72 ommit callback r
2c3b0 65 74 75 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72 6f eturned non-zero
2c3c0 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e 20 43 68 65 63 ..** <todo> Chec
2c3d0 6b 20 6f 6e 20 74 68 69 73 20 3c 2f 74 6f 64 6f k on this </todo
2c3e0 3e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f >.**.** See also
2c3f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 the [sqlite3_up
2c400 64 61 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 date_hook()] int
2c410 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 erface..**.** Re
2c420 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b quirements:.** [
2c430 48 31 32 39 35 31 5d 20 5b 48 31 32 39 35 32 5d H12951] [H12952]
2c440 20 5b 48 31 32 39 35 33 5d 20 5b 48 31 32 39 35 [H12953] [H1295
2c450 34 5d 20 5b 48 31 32 39 35 35 5d 0a 2a 2a 20 5b 4] [H12955].** [
2c460 48 31 32 39 36 31 5d 20 5b 48 31 32 39 36 32 5d H12961] [H12962]
2c470 20 5b 48 31 32 39 36 33 5d 20 5b 48 31 32 39 36 [H12963] [H1296
2c480 34 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 4].*/.SQLITE_API
2c490 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 void *sqlite3_c
2c4a0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 ommit_hook(sqlit
2c4b0 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 e3*, int(*)(void
2c4c0 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 *), void*);.SQLI
2c4d0 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c TE_API void *sql
2c4e0 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f ite3_rollback_ho
2c4f0 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 ok(sqlite3*, voi
2c500 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f d(*)(void *), vo
2c510 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 id*);../*.** CAP
2c520 49 33 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e I3REF: Data Chan
2c530 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 ge Notification
2c540 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 37 Callbacks {H1297
2c550 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 0} <S60400>.**.*
2c560 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 * The sqlite3_up
2c570 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 date_hook() inte
2c580 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 rface registers
2c590 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 a callback funct
2c5a0 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 ion.** with the
2c5b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2c5c0 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65 64 tion] identified
2c5d0 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 by the first ar
2c5e0 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 gument.** to be
2c5f0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 invoked whenever
2c600 20 61 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 a row is update
2c610 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 d, inserted or d
2c620 65 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 eleted..** Any c
2c630 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 allback set by a
2c640 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 previous call t
2c650 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a o this function.
2c660 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 ** for the same
2c670 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2c680 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 ion is overridde
2c690 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 n..**.** The sec
2c6a0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ond argument is
2c6b0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
2c6c0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 function to inv
2c6d0 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f oke when a.** ro
2c6e0 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e w is updated, in
2c6f0 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 serted or delete
2c700 64 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 d..** The first
2c710 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
2c720 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f callback is a co
2c730 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 py of the third
2c740 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 argument.** to s
2c750 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f qlite3_update_ho
2c760 6f 6b 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 ok()..** The sec
2c770 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 ond callback arg
2c780 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 ument is one of
2c790 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c [SQLITE_INSERT],
2c7a0 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d [SQLITE_DELETE]
2c7b0 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f ,.** or [SQLITE_
2c7c0 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 UPDATE], dependi
2c7d0 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 ng on the operat
2c7e0 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 ion that caused
2c7f0 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 the callback.**
2c800 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a to be invoked..*
2c810 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 * The third and
2c820 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 fourth arguments
2c830 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
2c840 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 contain pointer
2c850 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 s to the.** data
2c860 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e base and table n
2c870 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 ame containing t
2c880 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e he affected row.
2c890 0a 2a 2a 20 54 68 65 20 66 69 6e 61 6c 20 63 61 .** The final ca
2c8a0 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 llback parameter
2c8b0 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 is the [rowid]
2c8c0 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 49 of the row..** I
2c8d0 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e n the case of an
2c8e0 20 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 73 update, this is
2c8f0 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 74 the [rowid] aft
2c900 65 72 20 74 68 65 20 75 70 64 61 74 65 20 74 61 er the update ta
2c910 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a kes place..**.**
2c920 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b The update hook
2c930 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 is not invoked
2c940 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 when internal sy
2c950 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a stem tables are.
2c960 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 ** modified (i.e
2c970 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 . sqlite_master
2c980 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 and sqlite_seque
2c990 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 nce)..**.** In t
2c9a0 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 he current imple
2c9b0 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68 65 20 75 mentation, the u
2c9c0 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 73 pdate hook.** is
2c9d0 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 not invoked whe
2c9e0 6e 20 64 75 70 6c 69 63 61 74 69 6f 6e 20 72 6f n duplication ro
2c9f0 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 62 ws are deleted b
2ca00 65 63 61 75 73 65 20 6f 66 20 61 6e 0a 2a 2a 20 ecause of an.**
2ca10 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 7c 20 4f [ON CONFLICT | O
2ca20 4e 20 43 4f 4e 46 4c 49 43 54 20 52 45 50 4c 41 N CONFLICT REPLA
2ca30 43 45 5d 20 63 6c 61 75 73 65 2e 20 20 4e 6f 72 CE] clause. Nor
2ca40 20 69 73 20 74 68 65 20 75 70 64 61 74 65 20 68 is the update h
2ca50 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 77 ook.** invoked w
2ca60 68 65 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c hen rows are del
2ca70 65 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b eted using the [
2ca80 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a truncate optimiz
2ca90 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 65 ation]..** The e
2caa0 78 63 65 70 74 69 6f 6e 73 20 64 65 66 69 6e 65 xceptions define
2cab0 64 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 d in this paragr
2cac0 61 70 68 20 6d 69 67 68 74 20 63 68 61 6e 67 65 aph might change
2cad0 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 in a future.**
2cae0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 release of SQLit
2caf0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 e..**.** The upd
2cb00 61 74 65 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65 ate hook impleme
2cb10 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 ntation must not
2cb20 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 do anything tha
2cb30 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a t will modify.**
2cb40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
2cb50 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e nnection that in
2cb60 76 6f 6b 65 64 20 74 68 65 20 75 70 64 61 74 65 voked the update
2cb70 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 61 63 74 69 hook. Any acti
2cb80 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 ons.** to modify
2cb90 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
2cba0 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 nnection must be
2cbb0 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 deferred until
2cbc0 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d after the.** com
2cbd0 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b pletion of the [
2cbe0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
2cbf0 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 call that trigge
2cc00 72 65 64 20 74 68 65 20 75 70 64 61 74 65 20 68 red the update h
2cc10 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ook..** Note tha
2cc20 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 t [sqlite3_prepa
2cc30 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 re_v2()] and [sq
2cc40 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f lite3_step()] bo
2cc50 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a th modify their.
2cc60 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ** database conn
2cc70 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 ections for the
2cc80 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 meaning of "modi
2cc90 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 fy" in this para
2cca0 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 graph..**.** If
2ccb0 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e another function
2ccc0 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 was previously
2ccd0 72 65 67 69 73 74 65 72 65 64 2c 20 69 74 73 20 registered, its
2cce0 70 41 72 67 20 76 61 6c 75 65 0a 2a 2a 20 69 73 pArg value.** is
2ccf0 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 returned. Othe
2cd00 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 rwise NULL is re
2cd10 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 turned..**.** Se
2cd20 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 e also the [sqli
2cd30 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 te3_commit_hook(
2cd40 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
2cd50 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d rollback_hook()]
2cd60 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a .** interfaces..
2cd70 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e **.** Requiremen
2cd80 74 73 3a 0a 2a 2a 20 5b 48 31 32 39 37 31 5d 20 ts:.** [H12971]
2cd90 5b 48 31 32 39 37 33 5d 20 5b 48 31 32 39 37 35 [H12973] [H12975
2cda0 5d 20 5b 48 31 32 39 37 37 5d 20 5b 48 31 32 39 ] [H12977] [H129
2cdb0 37 39 5d 20 5b 48 31 32 39 38 31 5d 20 5b 48 31 79] [H12981] [H1
2cdc0 32 39 38 33 5d 20 5b 48 31 32 39 38 36 5d 0a 2a 2983] [H12986].*
2cdd0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 /.SQLITE_API voi
2cde0 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 64 61 74 d *sqlite3_updat
2cdf0 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65 e_hook(. sqlite
2ce00 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 3*, . void(*)(v
2ce10 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20 oid *,int ,char
2ce20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e const *,char con
2ce30 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 st *,sqlite3_int
2ce40 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 64),. void*.);.
2ce50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2ce60 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 Enable Or Disab
2ce70 6c 65 20 53 68 61 72 65 64 20 50 61 67 65 72 20 le Shared Pager
2ce80 43 61 63 68 65 20 7b 48 31 30 33 33 30 7d 20 3c Cache {H10330} <
2ce90 53 33 30 39 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f S30900>.** KEYWO
2cea0 52 44 53 3a 20 7b 73 68 61 72 65 64 20 63 61 63 RDS: {shared cac
2ceb0 68 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 he}.**.** This r
2cec0 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f outine enables o
2ced0 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 73 r disables the s
2cee0 68 61 72 69 6e 67 20 6f 66 20 74 68 65 20 64 61 haring of the da
2cef0 74 61 62 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 tabase cache.**
2cf00 61 6e 64 20 73 63 68 65 6d 61 20 64 61 74 61 20 and schema data
2cf10 73 74 72 75 63 74 75 72 65 73 20 62 65 74 77 65 structures betwe
2cf20 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e en [database con
2cf30 6e 65 63 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 nection | connec
2cf40 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 tions].** to the
2cf50 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e 20 same database.
2cf60 53 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c Sharing is enabl
2cf70 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 ed if the argume
2cf80 6e 74 20 69 73 20 74 72 75 65 0a 2a 2a 20 61 6e nt is true.** an
2cf90 64 20 64 69 73 61 62 6c 65 64 20 69 66 20 74 68 d disabled if th
2cfa0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 66 61 e argument is fa
2cfb0 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20 43 61 63 68 65 lse..**.** Cache
2cfc0 20 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 sharing is enab
2cfd0 6c 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65 64 led and disabled
2cfe0 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20 70 for an entire p
2cff0 72 6f 63 65 73 73 2e 0a 2a 2a 20 54 68 69 73 20 rocess..** This
2d000 69 73 20 61 20 63 68 61 6e 67 65 20 61 73 20 6f is a change as o
2d010 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e f SQLite version
2d020 20 33 2e 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72 3.5.0. In prior
2d030 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
2d040 69 74 65 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20 ite,.** sharing
2d050 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 was enabled or d
2d060 69 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63 68 isabled for each
2d070 20 74 68 72 65 61 64 20 73 65 70 61 72 61 74 65 thread separate
2d080 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 ly..**.** The ca
2d090 63 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 che sharing mode
2d0a0 20 73 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 set by this int
2d0b0 65 72 66 61 63 65 20 65 66 66 65 63 74 73 20 61 erface effects a
2d0c0 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a ll subsequent.**
2d0d0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 calls to [sqlit
2d0e0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c e3_open()], [sql
2d0f0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c ite3_open_v2()],
2d100 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 and [sqlite3_op
2d110 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 en16()]..** Exis
2d120 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f ting database co
2d130 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e nnections contin
2d140 75 65 20 75 73 65 20 74 68 65 20 73 68 61 72 69 ue use the shari
2d150 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 ng mode.** that
2d160 77 61 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 was in effect at
2d170 20 74 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 the time they w
2d180 65 72 65 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a ere opened..**.*
2d190 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 * Virtual tables
2d1a0 20 63 61 6e 6e 6f 74 20 62 65 20 75 73 65 64 20 cannot be used
2d1b0 77 69 74 68 20 61 20 73 68 61 72 65 64 20 63 61 with a shared ca
2d1c0 63 68 65 2e 20 20 57 68 65 6e 20 73 68 61 72 65 che. When share
2d1d0 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e d.** cache is en
2d1e0 61 62 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c 69 abled, the [sqli
2d1f0 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c te3_create_modul
2d200 65 28 29 5d 20 41 50 49 20 75 73 65 64 20 74 6f e()] API used to
2d210 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 76 69 72 register.** vir
2d220 74 75 61 6c 20 74 61 62 6c 65 73 20 77 69 6c 6c tual tables will
2d230 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 61 always return a
2d240 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 n error..**.** T
2d250 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 his routine retu
2d260 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 rns [SQLITE_OK]
2d270 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65 20 if shared cache
2d280 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 was enabled or d
2d290 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65 isabled.** succe
2d2a0 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 ssfully. An [er
2d2b0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 ror code] is ret
2d2c0 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65 2e urned otherwise.
2d2d0 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65 64 20 63 61 .**.** Shared ca
2d2e0 63 68 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 che is disabled
2d2f0 62 79 20 64 65 66 61 75 6c 74 2e 20 42 75 74 20 by default. But
2d300 74 68 69 73 20 6d 69 67 68 74 20 63 68 61 6e 67 this might chang
2d310 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 e in.** future r
2d320 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 eleases of SQLit
2d330 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 e. Applications
2d340 20 74 68 61 74 20 63 61 72 65 20 61 62 6f 75 74 that care about
2d350 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 shared.** cache
2d360 20 73 65 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 setting should
2d370 73 65 74 20 69 74 20 65 78 70 6c 69 63 69 74 6c set it explicitl
2d380 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 y..**.** See Als
2d390 6f 3a 20 20 5b 53 51 4c 69 74 65 20 53 68 61 72 o: [SQLite Shar
2d3a0 65 64 2d 43 61 63 68 65 20 4d 6f 64 65 5d 0a 2a ed-Cache Mode].*
2d3b0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
2d3c0 73 3a 20 5b 48 31 30 33 33 31 5d 20 5b 48 31 30 s: [H10331] [H10
2d3d0 33 33 36 5d 20 5b 48 31 30 33 33 37 5d 20 5b 48 336] [H10337] [H
2d3e0 31 30 33 33 39 5d 0a 2a 2f 0a 53 51 4c 49 54 45 10339].*/.SQLITE
2d3f0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
2d400 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 _enable_shared_c
2d410 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a ache(int);../*.*
2d420 2a 20 43 41 50 49 33 52 45 46 3a 20 41 74 74 65 * CAPI3REF: Atte
2d430 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65 61 70 mpt To Free Heap
2d440 20 4d 65 6d 6f 72 79 20 7b 48 31 37 33 34 30 7d Memory {H17340}
2d450 20 3c 53 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 <S30220>.**.**
2d460 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 The sqlite3_rele
2d470 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 ase_memory() int
2d480 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 erface attempts
2d490 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73 0a to free N bytes.
2d4a0 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 ** of heap memor
2d4b0 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e y by deallocatin
2d4c0 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 g non-essential
2d4d0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
2d4e0 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 ns.** held by th
2d4f0 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 72 61 e database libra
2d500 72 79 2e 20 7b 45 4e 44 7d 20 20 4d 65 6d 6f 72 ry. {END} Memor
2d510 79 20 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 y used to cache
2d520 64 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 database.** page
2d530 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 s to improve per
2d540 66 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 formance is an e
2d550 78 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 xample of non-es
2d560 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a sential memory..
2d570 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 ** sqlite3_relea
2d580 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 se_memory() retu
2d590 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
2d5a0 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 f bytes actually
2d5b0 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 freed,.** which
2d5c0 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f might be more o
2d5d0 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 r less than the
2d5e0 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 amount requested
2d5f0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
2d600 65 6e 74 73 3a 20 5b 48 31 37 33 34 31 5d 20 5b ents: [H17341] [
2d610 48 31 37 33 34 32 5d 0a 2a 2f 0a 53 51 4c 49 54 H17342].*/.SQLIT
2d620 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
2d630 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 3_release_memory
2d640 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 (int);../*.** CA
2d650 50 49 33 52 45 46 3a 20 49 6d 70 6f 73 65 20 41 PI3REF: Impose A
2d660 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 Limit On Heap S
2d670 69 7a 65 20 7b 48 31 37 33 35 30 7d 20 3c 53 33 ize {H17350} <S3
2d680 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 0220>.**.** The
2d690 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 sqlite3_soft_hea
2d6a0 70 5f 6c 69 6d 69 74 28 29 20 69 6e 74 65 72 66 p_limit() interf
2d6b0 61 63 65 20 70 6c 61 63 65 73 20 61 20 22 73 6f ace places a "so
2d6c0 66 74 22 20 6c 69 6d 69 74 0a 2a 2a 20 6f 6e 20 ft" limit.** on
2d6d0 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 the amount of he
2d6e0 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d ap memory that m
2d6f0 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 ay be allocated
2d700 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 49 66 by SQLite..** If
2d710 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c an internal all
2d720 6f 63 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 ocation is reque
2d730 73 74 65 64 20 74 68 61 74 20 77 6f 75 6c 64 20 sted that would
2d740 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 73 6f exceed the.** so
2d750 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 5b ft heap limit, [
2d760 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f sqlite3_release_
2d770 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20 69 6e 76 memory()] is inv
2d780 6f 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a 2a 20 6d oked one or.** m
2d790 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 66 72 65 ore times to fre
2d7a0 65 20 75 70 20 73 6f 6d 65 20 73 70 61 63 65 20 e up some space
2d7b0 62 65 66 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63 before the alloc
2d7c0 61 74 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d ation is perform
2d7d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 ed..**.** The li
2d7e0 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22 73 mit is called "s
2d7f0 6f 66 74 22 2c 20 62 65 63 61 75 73 65 20 69 66 oft", because if
2d800 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 [sqlite3_releas
2d810 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2a 20 63 e_memory()].** c
2d820 61 6e 6e 6f 74 20 66 72 65 65 20 73 75 66 66 69 annot free suffi
2d830 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 cient memory to
2d840 70 72 65 76 65 6e 74 20 74 68 65 20 6c 69 6d 69 prevent the limi
2d850 74 20 66 72 6f 6d 20 62 65 69 6e 67 20 65 78 63 t from being exc
2d860 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 eeded,.** the me
2d870 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 mory is allocate
2d880 64 20 61 6e 79 77 61 79 20 61 6e 64 20 74 68 65 d anyway and the
2d890 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 current operati
2d8a0 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a on proceeds..**.
2d8b0 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20 6f 72 ** A negative or
2d8c0 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 zero value for
2d8d0 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 N means that the
2d8e0 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20 68 65 re is no soft he
2d8f0 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 ap limit and.**
2d900 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 [sqlite3_release
2d910 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 _memory()] will
2d920 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 only be called w
2d930 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65 78 hen memory is ex
2d940 68 61 75 73 74 65 64 2e 0a 2a 2a 20 54 68 65 20 hausted..** The
2d950 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f default value fo
2d960 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 r the soft heap
2d970 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a limit is zero..*
2d980 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 *.** SQLite make
2d990 73 20 61 20 62 65 73 74 20 65 66 66 6f 72 74 20 s a best effort
2d9a0 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f 66 to honor the sof
2d9b0 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 0a 2a 2a t heap limit..**
2d9c0 20 42 75 74 20 69 66 20 74 68 65 20 73 6f 66 74 But if the soft
2d9d0 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61 6e 6e heap limit cann
2d9e0 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64 2c 20 65 ot be honored, e
2d9f0 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a xecution will.**
2da00 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f 75 continue withou
2da10 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69 66 t error or notif
2da20 69 63 61 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 ication. This i
2da30 73 20 77 68 79 20 74 68 65 20 6c 69 6d 69 74 20 s why the limit
2da40 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20 61 20 22 is.** called a "
2da50 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20 49 74 soft" limit. It
2da60 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c is advisory onl
2da70 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 y..**.** Prior t
2da80 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e o SQLite version
2da90 20 33 2e 35 2e 30 2c 20 74 68 69 73 20 72 6f 75 3.5.0, this rou
2daa0 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73 74 72 tine only constr
2dab0 61 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f 72 79 ained the memory
2dac0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 .** allocated by
2dad0 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 a single thread
2dae0 20 2d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 - the same thre
2daf0 61 64 20 69 6e 20 77 68 69 63 68 20 74 68 69 73 ad in which this
2db00 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75 6e 73 routine.** runs
2db10 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 . Beginning wit
2db20 68 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e h SQLite version
2db30 20 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f 66 74 3.5.0, the soft
2db40 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 0a 2a heap limit is.*
2db50 2a 20 61 70 70 6c 69 65 64 20 74 6f 20 61 6c 6c * applied to all
2db60 20 74 68 72 65 61 64 73 2e 20 54 68 65 20 76 61 threads. The va
2db70 6c 75 65 20 73 70 65 63 69 66 69 65 64 20 66 6f lue specified fo
2db80 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 r the soft heap
2db90 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e 20 75 limit.** is an u
2dba0 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 pper bound on th
2dbb0 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79 20 61 e total memory a
2dbc0 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 6c llocation for al
2dbd0 6c 20 74 68 72 65 61 64 73 2e 20 49 6e 0a 2a 2a l threads. In.**
2dbe0 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 74 version 3.5.0 t
2dbf0 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 63 68 61 here is no mecha
2dc00 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74 69 6e nism for limitin
2dc10 67 20 74 68 65 20 68 65 61 70 20 75 73 61 67 65 g the heap usage
2dc20 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 64 75 for.** individu
2dc30 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a 0a 2a al threads..**.*
2dc40 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a * Requirements:.
2dc50 2a 2a 20 5b 48 31 36 33 35 31 5d 20 5b 48 31 36 ** [H16351] [H16
2dc60 33 35 32 5d 20 5b 48 31 36 33 35 33 5d 20 5b 48 352] [H16353] [H
2dc70 31 36 33 35 34 5d 20 5b 48 31 36 33 35 35 5d 20 16354] [H16355]
2dc80 5b 48 31 36 33 35 38 5d 0a 2a 2f 0a 53 51 4c 49 [H16358].*/.SQLI
2dc90 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 TE_API void sqli
2dca0 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 te3_soft_heap_li
2dcb0 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a mit(int);../*.**
2dcc0 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 72 61 CAPI3REF: Extra
2dcd0 63 74 20 4d 65 74 61 64 61 74 61 20 41 62 6f 75 ct Metadata Abou
2dce0 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 t A Column Of A
2dcf0 54 61 62 6c 65 20 7b 48 31 32 38 35 30 7d 20 3c Table {H12850} <
2dd00 53 36 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S60300>.**.** Th
2dd10 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 is routine retur
2dd20 6e 73 20 6d 65 74 61 64 61 74 61 20 61 62 6f 75 ns metadata abou
2dd30 74 20 61 20 73 70 65 63 69 66 69 63 20 63 6f 6c t a specific col
2dd40 75 6d 6e 20 6f 66 20 61 20 73 70 65 63 69 66 69 umn of a specifi
2dd50 63 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 74 61 c.** database ta
2dd60 62 6c 65 20 61 63 63 65 73 73 69 62 6c 65 20 75 ble accessible u
2dd70 73 69 6e 67 20 74 68 65 20 5b 64 61 74 61 62 61 sing the [databa
2dd80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 se connection] h
2dd90 61 6e 64 6c 65 0a 2a 2a 20 70 61 73 73 65 64 20 andle.** passed
2dda0 61 73 20 74 68 65 20 66 69 72 73 74 20 66 75 6e as the first fun
2ddb0 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a ction argument..
2ddc0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6c 75 6d 6e **.** The column
2ddd0 20 69 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 is identified b
2dde0 79 20 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 y the second, th
2ddf0 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 ird and fourth p
2de00 61 72 61 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20 arameters to.**
2de10 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54 this function. T
2de20 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
2de30 74 65 72 20 69 73 20 65 69 74 68 65 72 20 74 68 ter is either th
2de40 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 e name of the da
2de50 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 tabase.** (i.e.
2de60 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 20 6f "main", "temp" o
2de70 72 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 r an attached da
2de80 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 tabase) containi
2de90 6e 67 20 74 68 65 20 73 70 65 63 69 66 69 65 64 ng the specified
2dea0 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c .** table or NUL
2deb0 4c 2e 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c L. If it is NULL
2dec0 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 , then all attac
2ded0 68 65 64 20 64 61 74 61 62 61 73 65 73 20 61 72 hed databases ar
2dee0 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f e searched.** fo
2def0 72 20 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e r the table usin
2df00 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 g the same algor
2df10 69 74 68 6d 20 75 73 65 64 20 62 79 20 74 68 65 ithm used by the
2df20 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 database engine
2df30 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 to.** resolve u
2df40 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65 nqualified table
2df50 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a references..**.
2df60 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 ** The third and
2df70 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
2df80 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 rs to this funct
2df90 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c ion are the tabl
2dfa0 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 e and column.**
2dfb0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69 name of the desi
2dfc0 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 red column, resp
2dfd0 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 ectively. Neithe
2dfe0 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d r of these param
2dff0 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62 65 20 eters.** may be
2e000 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74 61 NULL..**.** Meta
2e010 64 61 74 61 20 69 73 20 72 65 74 75 72 6e 65 64 data is returned
2e020 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20 74 by writing to t
2e030 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 he memory locati
2e040 6f 6e 73 20 70 61 73 73 65 64 20 61 73 20 74 68 ons passed as th
2e050 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62 e 5th.** and sub
2e060 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65 sequent paramete
2e070 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 rs to this funct
2e080 69 6f 6e 2e 20 41 6e 79 20 6f 66 20 74 68 65 73 ion. Any of thes
2e090 65 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 e arguments may
2e0a0 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 be.** NULL, in w
2e0b0 68 69 63 68 20 63 61 73 65 20 74 68 65 20 63 6f hich case the co
2e0c0 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d rresponding elem
2e0d0 65 6e 74 20 6f 66 20 6d 65 74 61 64 61 74 61 20 ent of metadata
2e0e0 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a is omitted..**.*
2e0f0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a * <blockquote>.*
2e100 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d * <table border=
2e110 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e "1">.** <tr><th>
2e120 20 50 61 72 61 6d 65 74 65 72 20 3c 74 68 3e 20 Parameter <th>
2e130 4f 75 74 70 75 74 3c 62 72 3e 54 79 70 65 20 3c Output<br>Type <
2e140 74 68 3e 20 20 44 65 73 63 72 69 70 74 69 6f 6e th> Description
2e150 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 .**.** <tr><td>
2e160 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 5th <td> const c
2e170 68 61 72 2a 20 3c 74 64 3e 20 44 61 74 61 20 74 har* <td> Data t
2e180 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 ype.** <tr><td>
2e190 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 6th <td> const c
2e1a0 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20 6f har* <td> Name o
2e1b0 66 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 f default collat
2e1c0 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a 20 ion sequence.**
2e1d0 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74 64 <tr><td> 7th <td
2e1e0 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 > int <t
2e1f0 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d d> True if colum
2e200 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c n has a NOT NULL
2e210 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 3c constraint.** <
2e220 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64 3e tr><td> 8th <td>
2e230 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 int <td
2e240 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e > True if column
2e250 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 is part of the
2e260 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 3c PRIMARY KEY.** <
2e270 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64 3e tr><td> 9th <td>
2e280 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 int <td
2e290 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e > True if column
2e2a0 20 69 73 20 5b 41 55 54 4f 49 4e 43 52 45 4d 45 is [AUTOINCREME
2e2b0 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a NT].** </table>.
2e2c0 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e ** </blockquote>
2e2d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 .**.** The memor
2e2e0 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 y pointed to by
2e2f0 74 68 65 20 63 68 61 72 61 63 74 65 72 20 70 6f the character po
2e300 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 inters returned
2e310 66 6f 72 20 74 68 65 0a 2a 2a 20 64 65 63 6c 61 for the.** decla
2e320 72 61 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 ration type and
2e330 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e collation sequen
2e340 63 65 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 ce is valid only
2e350 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 0a until the next.
2e360 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 53 ** call to any S
2e370 51 4c 69 74 65 20 41 50 49 20 66 75 6e 63 74 69 QLite API functi
2e380 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 on..**.** If the
2e390 20 73 70 65 63 69 66 69 65 64 20 74 61 62 6c 65 specified table
2e3a0 20 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76 is actually a v
2e3b0 69 65 77 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 iew, an [error c
2e3c0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 ode] is returned
2e3d0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 ..**.** If the s
2e3e0 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 pecified column
2e3f0 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 is "rowid", "oid
2e400 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 " or "_rowid_" a
2e410 6e 64 20 61 6e 0a 2a 2a 20 5b 49 4e 54 45 47 45 nd an.** [INTEGE
2e420 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 R PRIMARY KEY] c
2e430 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 65 olumn has been e
2e440 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 xplicitly declar
2e450 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 ed, then the out
2e460 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 put.** parameter
2e470 73 20 61 72 65 20 73 65 74 20 66 6f 72 20 74 68 s are set for th
2e480 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 e explicitly dec
2e490 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 49 66 lared column. If
2e4a0 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 there is no.**
2e4b0 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 explicitly decla
2e4c0 72 65 64 20 5b 49 4e 54 45 47 45 52 20 50 52 49 red [INTEGER PRI
2e4d0 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e MARY KEY] column
2e4e0 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 , then the outpu
2e4f0 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 t.** parameters
2e500 61 72 65 20 73 65 74 20 61 73 20 66 6f 6c 6c 6f are set as follo
2e510 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a ws:.**.** <pre>.
2e520 2a 2a 20 20 20 20 20 64 61 74 61 20 74 79 70 65 ** data type
2e530 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 : "INTEGER".**
2e540 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 collation seq
2e550 75 65 6e 63 65 3a 20 22 42 49 4e 41 52 59 22 0a uence: "BINARY".
2e560 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a ** not null:
2e570 20 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 0.** primar
2e580 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 y key: 1.**
2e590 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 auto increment:
2e5a0 30 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 0.** </pre>.**.*
2e5b0 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 * This function
2e5c0 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 may load one or
2e5d0 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f more schemas fro
2e5e0 6d 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 m database files
2e5f0 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 . If an.** error
2e600 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 occurs during t
2e610 68 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 his process, or
2e620 69 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64 if the requested
2e630 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e table or column
2e640 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f .** cannot be fo
2e650 75 6e 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 und, an [error c
2e660 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 ode] is returned
2e670 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 and an error me
2e680 73 73 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69 6e ssage left.** in
2e690 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
2e6a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20 62 onnection] (to b
2e6b0 65 20 72 65 74 72 69 65 76 65 64 20 75 73 69 6e e retrieved usin
2e6c0 67 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 g sqlite3_errmsg
2e6d0 28 29 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ())..**.** This
2e6e0 41 50 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 API is only avai
2e6f0 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 lable if the lib
2e700 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 rary was compile
2e710 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 d with the.** [S
2e720 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c QLITE_ENABLE_COL
2e730 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d UMN_METADATA] C-
2e740 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d preprocessor sym
2e750 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a bol defined..*/.
2e760 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
2e770 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c qlite3_table_col
2e780 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 umn_metadata(.
2e790 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
2e7a0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 /* C
2e7b0 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 onnection handle
2e7c0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
2e7d0 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 *zDbName,
2e7e0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6e 61 /* Database na
2e7f0 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 me or NULL */.
2e800 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 const char *zTab
2e810 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 leName, /* T
2e820 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 able name */. c
2e830 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 onst char *zColu
2e840 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f mnName, /* Co
2e850 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 lumn name */. c
2e860 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 har const **pzDa
2e870 74 61 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 taType, /* OU
2e880 54 50 55 54 3a 20 44 65 63 6c 61 72 65 64 20 64 TPUT: Declared d
2e890 61 74 61 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 ata type */. ch
2e8a0 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c ar const **pzCol
2e8b0 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 lSeq, /* OUT
2e8c0 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 PUT: Collation s
2e8d0 65 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a equence name */.
2e8e0 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c int *pNotNull,
2e8f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
2e900 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 OUTPUT: True if
2e910 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 NOT NULL constr
2e920 61 69 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a 20 aint exists */.
2e930 20 69 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b 65 int *pPrimaryKe
2e940 79 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 y, /*
2e950 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 OUTPUT: True if
2e960 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20 50 column part of P
2e970 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74 K */. int *pAut
2e980 6f 69 6e 63 20 20 20 20 20 20 20 20 20 20 20 20 oinc
2e990 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 /* OUTPUT: Tr
2e9a0 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 ue if column is
2e9b0 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a auto-increment *
2e9c0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.);../*.** CAPI
2e9d0 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78 3REF: Load An Ex
2e9e0 74 65 6e 73 69 6f 6e 20 7b 48 31 32 36 30 30 7d tension {H12600}
2e9f0 20 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S20500>.**.**
2ea00 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6c This interface l
2ea10 6f 61 64 73 20 61 6e 20 53 51 4c 69 74 65 20 65 oads an SQLite e
2ea20 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 xtension library
2ea30 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d 65 64 20 from the named
2ea40 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 file..**.** {H12
2ea50 36 30 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 601} The sqlite3
2ea60 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 _load_extension(
2ea70 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 ) interface atte
2ea80 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a mpts to load an.
2ea90 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 69 ** SQLi
2eaa0 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 te extension lib
2eab0 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64 20 69 rary contained i
2eac0 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 69 6c 65 n the file zFile
2ead0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 32 7d ..**.** {H12602}
2eae0 20 54 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 The entry point
2eaf0 20 69 73 20 7a 50 72 6f 63 2e 0a 2a 2a 0a 2a 2a is zProc..**.**
2eb00 20 7b 48 31 32 36 30 33 7d 20 7a 50 72 6f 63 20 {H12603} zProc
2eb10 6d 61 79 20 62 65 20 30 2c 20 69 6e 20 77 68 69 may be 0, in whi
2eb20 63 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65 ch case the name
2eb30 20 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f of the entry po
2eb40 69 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 int.**
2eb50 64 65 66 61 75 6c 74 73 20 74 6f 20 22 73 71 6c defaults to "sql
2eb60 69 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 ite3_extension_i
2eb70 6e 69 74 22 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 nit"..**.** {H12
2eb80 36 30 34 7d 20 54 68 65 20 73 71 6c 69 74 65 33 604} The sqlite3
2eb90 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 _load_extension(
2eba0 29 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c ) interface shal
2ebb0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 l return.**
2ebc0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d [SQLITE_OK]
2ebd0 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 on success and
2ebe0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 [SQLITE_ERROR] i
2ebf0 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 f something goes
2ec00 20 77 72 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 wrong..**.** {H
2ec10 31 32 36 30 35 7d 20 49 66 20 61 6e 20 65 72 72 12605} If an err
2ec20 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70 7a or occurs and pz
2ec30 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c ErrMsg is not 0,
2ec40 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 then the.**
2ec50 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6c [sqlite3_l
2ec60 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d oad_extension()]
2ec70 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c interface shall
2ec80 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 20 attempt to.**
2ec90 20 20 20 20 20 20 20 20 66 69 6c 6c 20 2a 70 7a fill *pz
2eca0 45 72 72 4d 73 67 20 77 69 74 68 20 65 72 72 6f ErrMsg with erro
2ecb0 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 73 r message text s
2ecc0 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a tored in memory.
2ecd0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62 74 61 ** obta
2ece0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 ined from [sqlit
2ecf0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 7b 45 e3_malloc()]. {E
2ed00 4e 44 7d 20 20 54 68 65 20 63 61 6c 6c 69 6e 67 ND} The calling
2ed10 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 function.**
2ed20 20 20 20 20 20 20 73 68 6f 75 6c 64 20 66 72 65 should fre
2ed30 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 20 62 79 e this memory by
2ed40 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
2ed50 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 3_free()]..**.**
2ed60 20 7b 48 31 32 36 30 36 7d 20 45 78 74 65 6e 73 {H12606} Extens
2ed70 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 ion loading must
2ed80 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e be enabled usin
2ed90 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 g.** [s
2eda0 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f qlite3_enable_lo
2edb0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 ad_extension()]
2edc0 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 prior to calling
2edd0 20 74 68 69 73 20 41 50 49 2c 0a 2a 2a 20 20 20 this API,.**
2ede0 20 20 20 20 20 20 20 6f 74 68 65 72 77 69 73 65 otherwise
2edf0 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 an error will b
2ee00 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 53 e returned..*/.S
2ee10 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
2ee20 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e lite3_load_exten
2ee30 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 sion(. sqlite3
2ee40 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a *db, /*
2ee50 20 4c 6f 61 64 20 74 68 65 20 65 78 74 65 6e 73 Load the extens
2ee60 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20 64 61 ion into this da
2ee70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2ee80 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 n */. const cha
2ee90 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a 20 r *zFile, /*
2eea0 4e 61 6d 65 20 6f 66 20 74 68 65 20 73 68 61 72 Name of the shar
2eeb0 65 64 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 ed library conta
2eec0 69 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e 20 ining extension
2eed0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
2eee0 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45 6e *zProc, /* En
2eef0 74 72 79 20 70 6f 69 6e 74 2e 20 20 44 65 72 69 try point. Deri
2ef00 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20 69 ved from zFile i
2ef10 66 20 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a f 0 */. char **
2ef20 70 7a 45 72 72 4d 73 67 20 20 20 20 20 20 20 2f pzErrMsg /
2ef30 2a 20 50 75 74 20 65 72 72 6f 72 20 6d 65 73 73 * Put error mess
2ef40 61 67 65 20 68 65 72 65 20 69 66 20 6e 6f 74 20 age here if not
2ef50 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 0 */.);../*.** C
2ef60 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 API3REF: Enable
2ef70 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e Or Disable Exten
2ef80 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b 48 31 sion Loading {H1
2ef90 32 36 32 30 7d 20 3c 53 32 30 35 30 30 3e 0a 2a 2620} <S20500>.*
2efa0 2a 0a 2a 2a 20 53 6f 20 61 73 20 6e 6f 74 20 74 *.** So as not t
2efb0 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 74 79 20 o open security
2efc0 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20 61 holes in older a
2efd0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 pplications that
2efe0 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72 are.** unprepar
2eff0 65 64 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 ed to deal with
2f000 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e extension loadin
2f010 67 2c 20 61 6e 64 20 61 73 20 61 20 6d 65 61 6e g, and as a mean
2f020 73 20 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a s of disabling.*
2f030 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 * extension load
2f040 69 6e 67 20 77 68 69 6c 65 20 65 76 61 6c 75 61 ing while evalua
2f050 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 65 72 65 ting user-entere
2f060 64 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f d SQL, the follo
2f070 77 69 6e 67 20 41 50 49 0a 2a 2a 20 69 73 20 70 wing API.** is p
2f080 72 6f 76 69 64 65 64 20 74 6f 20 74 75 72 6e 20 rovided to turn
2f090 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 the [sqlite3_loa
2f0a0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d d_extension()] m
2f0b0 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 20 echanism on and
2f0c0 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 45 78 74 65 6e off..**.** Exten
2f0d0 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20 sion loading is
2f0e0 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e 20 off by default.
2f0f0 53 65 65 20 74 69 63 6b 65 74 20 23 31 38 36 33 See ticket #1863
2f100 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 32 31 7d ..**.** {H12621}
2f110 20 43 61 6c 6c 20 74 68 65 20 73 71 6c 69 74 65 Call the sqlite
2f120 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 3_enable_load_ex
2f130 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e tension() routin
2f140 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a e with onoff==1.
2f150 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 ** to t
2f160 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f urn extension lo
2f170 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63 61 6c ading on and cal
2f180 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66 3d l it with onoff=
2f190 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 20 20 =0 to turn.**
2f1a0 20 20 20 20 20 20 20 69 74 20 62 61 63 6b 20 6f it back o
2f1b0 66 66 20 61 67 61 69 6e 2e 0a 2a 2a 0a 2a 2a 20 ff again..**.**
2f1c0 7b 48 31 32 36 32 32 7d 20 45 78 74 65 6e 73 69 {H12622} Extensi
2f1d0 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20 6f 66 on loading is of
2f1e0 66 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2f f by default..*/
2f1f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
2f200 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c sqlite3_enable_l
2f210 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71 oad_extension(sq
2f220 6c 69 74 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f lite3 *db, int o
2f230 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 noff);../*.** CA
2f240 50 49 33 52 45 46 3a 20 41 75 74 6f 6d 61 74 69 PI3REF: Automati
2f250 63 61 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78 cally Load An Ex
2f260 74 65 6e 73 69 6f 6e 73 20 7b 48 31 32 36 34 30 tensions {H12640
2f270 7d 20 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a } <S20500>.**.**
2f280 20 54 68 69 73 20 41 50 49 20 63 61 6e 20 62 65 This API can be
2f290 20 69 6e 76 6f 6b 65 64 20 61 74 20 70 72 6f 67 invoked at prog
2f2a0 72 61 6d 20 73 74 61 72 74 75 70 20 69 6e 20 6f ram startup in o
2f2b0 72 64 65 72 20 74 6f 20 72 65 67 69 73 74 65 72 rder to register
2f2c0 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 .** one or more
2f2d0 73 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 statically linke
2f2e0 64 20 65 78 74 65 6e 73 69 6f 6e 73 20 74 68 61 d extensions tha
2f2f0 74 20 77 69 6c 6c 20 62 65 20 61 76 61 69 6c 61 t will be availa
2f300 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65 ble.** to all ne
2f310 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e w [database conn
2f320 65 63 74 69 6f 6e 73 5d 2e 20 7b 45 4e 44 7d 0a ections]. {END}.
2f330 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
2f340 6e 65 20 73 74 6f 72 65 73 20 61 20 70 6f 69 6e ne stores a poin
2f350 74 65 72 20 74 6f 20 74 68 65 20 65 78 74 65 6e ter to the exten
2f360 73 69 6f 6e 20 69 6e 20 61 6e 20 61 72 72 61 79 sion in an array
2f370 20 74 68 61 74 20 69 73 0a 2a 2a 20 6f 62 74 61 that is.** obta
2f380 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 ined from [sqlit
2f390 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 49 e3_malloc()]. I
2f3a0 66 20 79 6f 75 20 72 75 6e 20 61 20 6d 65 6d 6f f you run a memo
2f3b0 72 79 20 6c 65 61 6b 20 63 68 65 63 6b 65 72 0a ry leak checker.
2f3c0 2a 2a 20 6f 6e 20 79 6f 75 72 20 70 72 6f 67 72 ** on your progr
2f3d0 61 6d 20 61 6e 64 20 69 74 20 72 65 70 6f 72 74 am and it report
2f3e0 73 20 61 20 6c 65 61 6b 20 62 65 63 61 75 73 65 s a leak because
2f3f0 20 6f 66 20 74 68 69 73 20 61 72 72 61 79 2c 20 of this array,
2f400 69 6e 76 6f 6b 65 0a 2a 2a 20 5b 73 71 6c 69 74 invoke.** [sqlit
2f410 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 e3_reset_auto_ex
2f420 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 tension()] prior
2f430 20 74 6f 20 73 68 75 74 64 6f 77 6e 20 74 6f 20 to shutdown to
2f440 66 72 65 65 20 74 68 65 20 6d 65 6d 6f 72 79 2e free the memory.
2f450 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34 31 7d 20 .**.** {H12641}
2f460 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 This function re
2f470 67 69 73 74 65 72 73 20 61 6e 20 65 78 74 65 6e gisters an exten
2f480 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74 sion entry point
2f490 20 74 68 61 74 20 69 73 0a 2a 2a 20 20 20 20 20 that is.**
2f4a0 20 20 20 20 20 61 75 74 6f 6d 61 74 69 63 61 6c automatical
2f4b0 6c 79 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 ly invoked whene
2f4c0 76 65 72 20 61 20 6e 65 77 20 5b 64 61 74 61 62 ver a new [datab
2f4d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a ase connection].
2f4e0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6f ** is o
2f4f0 70 65 6e 65 64 20 75 73 69 6e 67 20 5b 73 71 6c pened using [sql
2f500 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 ite3_open()], [s
2f510 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d qlite3_open16()]
2f520 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 ,.** or
2f530 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
2f540 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 2()]..**.** {H12
2f550 36 34 32 7d 20 44 75 70 6c 69 63 61 74 65 20 65 642} Duplicate e
2f560 78 74 65 6e 73 69 6f 6e 73 20 61 72 65 20 64 65 xtensions are de
2f570 74 65 63 74 65 64 20 73 6f 20 63 61 6c 6c 69 6e tected so callin
2f580 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a g this routine.*
2f590 2a 20 20 20 20 20 20 20 20 20 20 6d 75 6c 74 69 * multi
2f5a0 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68 20 74 ple times with t
2f5b0 68 65 20 73 61 6d 65 20 65 78 74 65 6e 73 69 6f he same extensio
2f5c0 6e 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 0a 2a n is harmless..*
2f5d0 2a 0a 2a 2a 20 7b 48 31 32 36 34 33 7d 20 54 68 *.** {H12643} Th
2f5e0 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 is routine store
2f5f0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 s a pointer to t
2f600 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20 he extension in
2f610 61 6e 20 61 72 72 61 79 0a 2a 2a 20 20 20 20 20 an array.**
2f620 20 20 20 20 20 74 68 61 74 20 69 73 20 6f 62 74 that is obt
2f630 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 ained from [sqli
2f640 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a te3_malloc()]..*
2f650 2a 0a 2a 2a 20 7b 48 31 32 36 34 34 7d 20 41 75 *.** {H12644} Au
2f660 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f tomatic extensio
2f670 6e 73 20 61 70 70 6c 79 20 61 63 72 6f 73 73 20 ns apply across
2f680 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a all threads..*/.
2f690 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
2f6a0 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 qlite3_auto_exte
2f6b0 6e 73 69 6f 6e 28 76 6f 69 64 20 28 2a 78 45 6e nsion(void (*xEn
2f6c0 74 72 79 50 6f 69 6e 74 29 28 76 6f 69 64 29 29 tryPoint)(void))
2f6d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2f6e0 46 3a 20 52 65 73 65 74 20 41 75 74 6f 6d 61 74 F: Reset Automat
2f6f0 69 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 ic Extension Loa
2f700 64 69 6e 67 20 7b 48 31 32 36 36 30 7d 20 3c 53 ding {H12660} <S
2f710 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 20500>.**.** Thi
2f720 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 s function disab
2f730 6c 65 73 20 61 6c 6c 20 70 72 65 76 69 6f 75 73 les all previous
2f740 6c 79 20 72 65 67 69 73 74 65 72 65 64 20 61 75 ly registered au
2f750 74 6f 6d 61 74 69 63 0a 2a 2a 20 65 78 74 65 6e tomatic.** exten
2f760 73 69 6f 6e 73 2e 20 7b 45 4e 44 7d 20 20 49 74 sions. {END} It
2f770 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 undoes the effe
2f780 63 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f 72 0a ct of all prior.
2f790 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f ** [sqlite3_auto
2f7a0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 63 61 _extension()] ca
2f7b0 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 lls..**.** {H126
2f7c0 36 31 7d 20 54 68 69 73 20 66 75 6e 63 74 69 6f 61} This functio
2f7d0 6e 20 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 70 n disables all p
2f7e0 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 reviously regist
2f7f0 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 ered.**
2f800 20 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e automatic exten
2f810 73 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 sions..**.** {H1
2f820 32 36 36 32 7d 20 54 68 69 73 20 66 75 6e 63 74 2662} This funct
2f830 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 75 74 ion disables aut
2f840 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e omatic extension
2f850 73 20 69 6e 20 61 6c 6c 20 74 68 72 65 61 64 73 s in all threads
2f860 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
2f870 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
2f880 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f et_auto_extensio
2f890 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 2a n(void);../*.***
2f8a0 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c *** EXPERIMENTAL
2f8b0 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 - subject to ch
2f8c0 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 ange without not
2f8d0 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ice ************
2f8e0 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 **.**.** The int
2f8f0 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 erface to the vi
2f900 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 rtual-table mech
2f910 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e 74 anism is current
2f920 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a ly considered.**
2f930 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e to be experimen
2f940 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 tal. The interf
2f950 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 ace might change
2f960 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 in incompatible
2f970 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 ways..** If thi
2f980 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 s is a problem f
2f990 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 or you, do not u
2f9a0 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 se the interface
2f9b0 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a at this time..*
2f9c0 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 *.** When the vi
2f9d0 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 rtual-table mech
2f9e0 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 anism stabilizes
2f9f0 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 , we will declar
2fa00 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 e the.** interfa
2fa10 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 ce fixed, suppor
2fa20 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c t it indefinitel
2fa30 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 y, and remove th
2fa40 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a is comment..*/..
2fa50 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73 /*.** Structures
2fa60 20 75 73 65 64 20 62 79 20 74 68 65 20 76 69 72 used by the vir
2fa70 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 tual table inter
2fa80 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20 face.*/.typedef
2fa90 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 struct sqlite3_v
2faa0 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62 tab sqlite3_vtab
2fab0 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 ;.typedef struct
2fac0 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 sqlite3_index_i
2fad0 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 nfo sqlite3_inde
2fae0 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20 x_info;.typedef
2faf0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 struct sqlite3_v
2fb00 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74 tab_cursor sqlit
2fb10 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a e3_vtab_cursor;.
2fb20 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
2fb30 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71 qlite3_module sq
2fb40 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f lite3_module;../
2fb50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 *.** CAPI3REF: V
2fb60 69 72 74 75 61 6c 20 54 61 62 6c 65 20 4f 62 6a irtual Table Obj
2fb70 65 63 74 20 7b 48 31 38 30 30 30 7d 20 3c 53 32 ect {H18000} <S2
2fb80 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 0400>.** KEYWORD
2fb90 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c S: sqlite3_modul
2fba0 65 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 e {virtual table
2fbb0 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 20 45 58 50 45 module}.** EXPE
2fbc0 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 RIMENTAL.**.** T
2fbd0 68 69 73 20 73 74 72 75 63 74 75 72 65 2c 20 73 his structure, s
2fbe0 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65 64 20 ometimes called
2fbf0 61 20 61 20 22 76 69 72 74 75 61 6c 20 74 61 62 a a "virtual tab
2fc00 6c 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20 le module", .**
2fc10 64 65 66 69 6e 65 73 20 74 68 65 20 69 6d 70 6c defines the impl
2fc20 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 20 ementation of a
2fc30 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d [virtual tables]
2fc40 2e 20 20 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 . .** This stru
2fc50 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73 20 6d cture consists m
2fc60 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 ostly of methods
2fc70 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e for the module.
2fc80 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61 6c .**.** A virtual
2fc90 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20 69 73 table module is
2fca0 20 63 72 65 61 74 65 64 20 62 79 20 66 69 6c 6c created by fill
2fcb0 69 6e 67 20 69 6e 20 61 20 70 65 72 73 69 73 74 ing in a persist
2fcc0 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 ent.** instance
2fcd0 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 of this structur
2fce0 65 20 61 6e 64 20 70 61 73 73 69 6e 67 20 61 20 e and passing a
2fcf0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 pointer to that
2fd00 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 6f 20 5b instance.** to [
2fd10 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d sqlite3_create_m
2fd20 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b 73 71 6c odule()] or [sql
2fd30 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 ite3_create_modu
2fd40 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 le_v2()]..** The
2fd50 20 72 65 67 69 73 74 72 61 74 69 6f 6e 20 72 65 registration re
2fd60 6d 61 69 6e 73 20 76 61 6c 69 64 20 75 6e 74 69 mains valid unti
2fd70 6c 20 69 74 20 69 73 20 72 65 70 6c 61 63 65 64 l it is replaced
2fd80 20 62 79 20 61 20 64 69 66 66 65 72 65 6e 74 0a by a different.
2fd90 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75 6e 74 ** module or unt
2fda0 69 6c 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 il the [database
2fdb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 6c 6f connection] clo
2fdc0 73 65 73 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e ses. The conten
2fdd0 74 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73 74 72 t.** of this str
2fde0 75 63 74 75 72 65 20 6d 75 73 74 20 6e 6f 74 20 ucture must not
2fdf0 63 68 61 6e 67 65 20 77 68 69 6c 65 20 69 74 20 change while it
2fe00 69 73 20 72 65 67 69 73 74 65 72 65 64 20 77 69 is registered wi
2fe10 74 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61 62 61 th.** any databa
2fe20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a se connection..*
2fe30 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 /.struct sqlite3
2fe40 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20 _module {. int
2fe50 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 iVersion;. int
2fe60 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69 74 (*xCreate)(sqlit
2fe70 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c e3*, void *pAux,
2fe80 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 .
2fe90 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 int argc, const
2fea0 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 char *const*argv
2feb0 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,.
2fec0 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a sqlite3_vtab **
2fed0 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b ppVTab, char**);
2fee0 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 . int (*xConnec
2fef0 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 t)(sqlite3*, voi
2ff00 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 d *pAux,.
2ff10 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 int argc
2ff20 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f , const char *co
2ff30 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 nst*argv,.
2ff40 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 sqlite3
2ff50 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 _vtab **ppVTab,
2ff60 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 char**);. int (
2ff70 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 71 6c *xBestIndex)(sql
2ff80 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 ite3_vtab *pVTab
2ff90 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f , sqlite3_index_
2ffa0 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a info*);. int (*
2ffb0 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c xDisconnect)(sql
2ffc0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 ite3_vtab *pVTab
2ffd0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73 74 );. int (*xDest
2ffe0 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74 61 roy)(sqlite3_vta
2fff0 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 b *pVTab);. int
30000 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 (*xOpen)(sqlite
30010 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 3_vtab *pVTab, s
30020 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 qlite3_vtab_curs
30030 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a or **ppCursor);.
30040 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 int (*xClose)(
30050 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 sqlite3_vtab_cur
30060 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 sor*);. int (*x
30070 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f Filter)(sqlite3_
30080 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e vtab_cursor*, in
30090 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 t idxNum, const
300a0 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20 20 char *idxStr,.
300b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e in
300c0 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33 5f t argc, sqlite3_
300d0 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20 value **argv);.
300e0 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73 71 int (*xNext)(sq
300f0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f lite3_vtab_curso
30100 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f r*);. int (*xEo
30110 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f f)(sqlite3_vtab_
30120 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 cursor*);. int
30130 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 (*xColumn)(sqlit
30140 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c e3_vtab_cursor*,
30150 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
30160 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 *, int);. int (
30170 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74 65 33 *xRowid)(sqlite3
30180 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 _vtab_cursor*, s
30190 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 52 qlite3_int64 *pR
301a0 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 owid);. int (*x
301b0 55 70 64 61 74 65 29 28 73 71 6c 69 74 65 33 5f Update)(sqlite3_
301c0 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c vtab *, int, sql
301d0 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 ite3_value **, s
301e0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b qlite3_int64 *);
301f0 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29 . int (*xBegin)
30200 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 (sqlite3_vtab *p
30210 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 VTab);. int (*x
30220 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76 74 Sync)(sqlite3_vt
30230 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e ab *pVTab);. in
30240 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c t (*xCommit)(sql
30250 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 ite3_vtab *pVTab
30260 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c );. int (*xRoll
30270 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 74 back)(sqlite3_vt
30280 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e ab *pVTab);. in
30290 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f t (*xFindFunctio
302a0 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 n)(sqlite3_vtab
302b0 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72 67 *pVtab, int nArg
302c0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
302d0 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20 20 ame,.
302e0 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 void
302f0 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c 69 (**pxFunc)(sqli
30300 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 te3_context*,int
30310 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a ,sqlite3_value**
30320 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 ),.
30330 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 2a void *
30340 2a 70 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 *ppArg);. int (
30350 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65 *xRename)(sqlite
30360 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 63 3_vtab *pVtab, c
30370 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 29 onst char *zNew)
30380 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ;.};../*.** CAPI
30390 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 3REF: Virtual Ta
303a0 62 6c 65 20 49 6e 64 65 78 69 6e 67 20 49 6e 66 ble Indexing Inf
303b0 6f 72 6d 61 74 69 6f 6e 20 7b 48 31 38 31 30 30 ormation {H18100
303c0 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 } <S20400>.** KE
303d0 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f YWORDS: sqlite3_
303e0 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a 20 45 58 index_info.** EX
303f0 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a PERIMENTAL.**.**
30400 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 The sqlite3_ind
30410 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72 ex_info structur
30420 65 20 61 6e 64 20 69 74 73 20 73 75 62 73 74 72 e and its substr
30430 75 63 74 75 72 65 73 20 69 73 20 75 73 65 64 20 uctures is used
30440 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72 to.** pass infor
30450 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 mation into and
30460 72 65 63 65 69 76 65 20 74 68 65 20 72 65 70 6c receive the repl
30470 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42 65 73 y from the [xBes
30480 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 68 6f tIndex].** metho
30490 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20 d of a [virtual
304a0 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 table module].
304b0 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65 72 The fields under
304c0 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65 20 **Inputs** are
304d0 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74 6f the.** inputs to
304e0 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64 20 xBestIndex and
304f0 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 are read-only.
30500 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65 72 xBestIndex inser
30510 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c 74 ts its.** result
30520 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75 74 s into the **Out
30530 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a puts** fields..*
30540 2a 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74 72 *.** The aConstr
30550 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 72 65 63 aint[] array rec
30560 6f 72 64 73 20 57 48 45 52 45 20 63 6c 61 75 73 ords WHERE claus
30570 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 6f 66 e constraints of
30580 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a the form:.**.**
30590 20 3c 70 72 65 3e 63 6f 6c 75 6d 6e 20 4f 50 20 <pre>column OP
305a0 65 78 70 72 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a expr</pre>.**.**
305b0 20 77 68 65 72 65 20 4f 50 20 69 73 20 3d 2c 20 where OP is =,
305c0 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67 74 <, <=, >
305d0 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 20 20 54 68 ;, or >=. Th
305e0 65 20 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65 e particular ope
305f0 72 61 74 6f 72 20 69 73 0a 2a 2a 20 73 74 6f 72 rator is.** stor
30600 65 64 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e ed in aConstrain
30610 74 5b 5d 2e 6f 70 2e 20 20 54 68 65 20 69 6e 64 t[].op. The ind
30620 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e ex of the column
30630 20 69 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a is stored in.**
30640 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 aConstraint[].i
30650 43 6f 6c 75 6d 6e 2e 20 20 61 43 6f 6e 73 74 72 Column. aConstr
30660 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73 aint[].usable is
30670 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a 20 TRUE if the.**
30680 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67 68 expr on the righ
30690 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e 20 t-hand side can
306a0 62 65 20 65 76 61 6c 75 61 74 65 64 20 28 61 6e be evaluated (an
306b0 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73 74 d thus the const
306c0 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62 raint.** is usab
306d0 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69 66 le) and false if
306e0 20 69 74 20 63 61 6e 6e 6f 74 2e 0a 2a 2a 0a 2a it cannot..**.*
306f0 2a 20 54 68 65 20 6f 70 74 69 6d 69 7a 65 72 20 * The optimizer
30700 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e automatically in
30710 76 65 72 74 73 20 74 65 72 6d 73 20 6f 66 20 74 verts terms of t
30720 68 65 20 66 6f 72 6d 20 22 65 78 70 72 20 4f 50 he form "expr OP
30730 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20 column".** and
30740 6d 61 6b 65 73 20 6f 74 68 65 72 20 73 69 6d 70 makes other simp
30750 6c 69 66 69 63 61 74 69 6f 6e 73 20 74 6f 20 74 lifications to t
30760 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 he WHERE clause
30770 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f in an attempt to
30780 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e 79 20 .** get as many
30790 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 WHERE clause ter
307a0 6d 73 20 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d ms into the form
307b0 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 73 20 shown above as
307c0 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 possible..** The
307d0 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 aConstraint[] a
307e0 72 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74 rray only report
307f0 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 s WHERE clause t
30800 65 72 6d 73 20 69 6e 20 74 68 65 20 63 6f 72 72 erms in the corr
30810 65 63 74 0a 2a 2a 20 66 6f 72 6d 20 74 68 61 74 ect.** form that
30820 20 72 65 66 65 72 20 74 6f 20 74 68 65 20 70 61 refer to the pa
30830 72 74 69 63 75 6c 61 72 20 76 69 72 74 75 61 6c rticular virtual
30840 20 74 61 62 6c 65 20 62 65 69 6e 67 20 71 75 65 table being que
30850 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 66 6f ried..**.** Info
30860 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 rmation about th
30870 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 e ORDER BY claus
30880 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 e is stored in a
30890 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 45 61 OrderBy[]..** Ea
308a0 63 68 20 74 65 72 6d 20 6f 66 20 61 4f 72 64 65 ch term of aOrde
308b0 72 42 79 20 72 65 63 6f 72 64 73 20 61 20 63 6f rBy records a co
308c0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44 45 lumn of the ORDE
308d0 52 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a R BY clause..**.
308e0 2a 2a 20 54 68 65 20 5b 78 42 65 73 74 49 6e 64 ** The [xBestInd
308f0 65 78 5d 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 ex] method must
30900 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74 fill aConstraint
30910 55 73 61 67 65 5b 5d 20 77 69 74 68 20 69 6e 66 Usage[] with inf
30920 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 ormation.** abou
30930 74 20 77 68 61 74 20 70 61 72 61 6d 65 74 65 72 t what parameter
30940 73 20 74 6f 20 70 61 73 73 20 74 6f 20 78 46 69 s to pass to xFi
30950 6c 74 65 72 2e 20 20 49 66 20 61 72 67 76 49 6e lter. If argvIn
30960 64 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 dex>0 then.** th
30970 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 e right-hand sid
30980 65 20 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70 e of the corresp
30990 6f 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 onding aConstrai
309a0 6e 74 5b 5d 20 69 73 20 65 76 61 6c 75 61 74 65 nt[] is evaluate
309b0 64 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 d.** and becomes
309c0 20 74 68 65 20 61 72 67 76 49 6e 64 65 78 2d 74 the argvIndex-t
309d0 68 20 65 6e 74 72 79 20 69 6e 20 61 72 67 76 2e h entry in argv.
309e0 20 20 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 If aConstraint
309f0 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 Usage[].omit.**
30a00 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 is true, then th
30a10 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 e constraint is
30a20 61 73 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75 assumed to be fu
30a30 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74 lly handled by t
30a40 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 he.** virtual ta
30a50 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 ble and is not c
30a60 68 65 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20 hecked again by
30a70 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 SQLite..**.** Th
30a80 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 e idxNum and idx
30a90 50 74 72 20 76 61 6c 75 65 73 20 61 72 65 20 72 Ptr values are r
30aa0 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73 ecorded and pass
30ab0 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b ed into the.** [
30ac0 78 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64 2e xFilter] method.
30ad0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 .** [sqlite3_fre
30ae0 65 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 e()] is used to
30af0 66 72 65 65 20 69 64 78 50 74 72 20 69 66 20 61 free idxPtr if a
30b00 6e 64 20 6f 6e 6c 79 20 69 66 66 0a 2a 2a 20 6e nd only iff.** n
30b10 65 65 64 54 6f 46 72 65 65 49 64 78 50 74 72 20 eedToFreeIdxPtr
30b20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 is true..**.** T
30b30 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d he orderByConsum
30b40 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20 6f 75 ed means that ou
30b50 74 70 75 74 20 66 72 6f 6d 20 5b 78 46 69 6c 74 tput from [xFilt
30b60 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69 6c 6c er]/[xNext] will
30b70 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68 65 occur in.** the
30b80 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20 74 correct order t
30b90 6f 20 73 61 74 69 73 66 79 20 74 68 65 20 4f 52 o satisfy the OR
30ba0 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 73 6f DER BY clause so
30bb0 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61 74 that no separat
30bc0 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74 65 e.** sorting ste
30bd0 70 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a p is required..*
30be0 2a 0a 2a 2a 20 54 68 65 20 65 73 74 69 6d 61 74 *.** The estimat
30bf0 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73 20 edCost value is
30c00 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 74 an estimate of t
30c10 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e 67 he cost of doing
30c20 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75 6c the.** particul
30c30 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66 75 ar lookup. A fu
30c40 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61 62 ll scan of a tab
30c50 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69 65 le with N entrie
30c60 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a 2a s should have.**
30c70 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20 41 a cost of N. A
30c80 20 62 69 6e 61 72 79 20 73 65 61 72 63 68 20 6f binary search o
30c90 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20 65 f a table of N e
30ca0 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 ntries should ha
30cb0 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66 20 ve a.** cost of
30cc0 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c 6f approximately lo
30cd0 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 g(N)..*/.struct
30ce0 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e sqlite3_index_in
30cf0 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74 73 fo {. /* Inputs
30d00 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73 74 */. int nConst
30d10 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20 raint;
30d20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65 6e /* Number of en
30d30 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74 72 tries in aConstr
30d40 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63 74 aint */. struct
30d50 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 sqlite3_index_c
30d60 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20 20 onstraint {.
30d70 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 int iColumn;
30d80 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f /* Co
30d90 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 6e lumn on left-han
30da0 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74 72 d side of constr
30db0 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e 73 aint */. uns
30dc0 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20 20 igned char op;
30dd0 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74 72 /* Constr
30de0 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a 2f aint operator */
30df0 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 . unsigned c
30e00 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20 20 har usable;
30e10 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69 73 20 /* True if this
30e20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75 73 constraint is us
30e30 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e 74 able */. int
30e40 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20 20 iTermOffset;
30e50 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69 /* Used i
30e60 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65 73 nternally - xBes
30e70 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69 67 tIndex should ig
30e80 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f nore */. } *aCo
30e90 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 nstraint;
30ea0 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f 66 /* Table of
30eb0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f WHERE clause co
30ec0 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20 69 nstraints */. i
30ed0 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20 20 nt nOrderBy;
30ee0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d /* Num
30ef0 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 ber of terms in
30f00 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 the ORDER BY cla
30f10 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 use */. struct
30f20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f 72 sqlite3_index_or
30f30 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69 6e 74 derby {. int
30f40 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 iColumn;
30f50 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e /* Column
30f60 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20 20 number */.
30f70 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 64 65 unsigned char de
30f80 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75 sc; /* Tru
30f90 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46 61 6c e for DESC. Fal
30fa0 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a 20 se for ASC. */.
30fb0 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20 20 20 } *aOrderBy;
30fc0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54 /* T
30fd0 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 he ORDER BY clau
30fe0 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70 75 se */. /* Outpu
30ff0 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 ts */. struct s
31000 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e qlite3_index_con
31010 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a straint_usage {.
31020 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64 65 int argvInde
31030 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 x; /*
31040 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e if >0, constrain
31050 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 72 67 t is part of arg
31060 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a v to xFilter */.
31070 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 unsigned cha
31080 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a 20 r omit; /*
31090 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20 74 65 Do not code a te
310a0 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f 6e 73 st for this cons
310b0 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a 61 traint */. } *a
310c0 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 3b ConstraintUsage;
310d0 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20 . int idxNum;
310e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
310f0 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f 20 Number used to
31100 69 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e 64 identify the ind
31110 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64 ex */. char *id
31120 78 53 74 72 3b 20 20 20 20 20 20 20 20 20 20 20 xStr;
31130 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f /* String, po
31140 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 20 ssibly obtained
31150 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c from sqlite3_mal
31160 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 loc */. int nee
31170 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20 20 dToFreeIdxStr;
31180 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78 53 /* Free idxS
31190 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 tr using sqlite3
311a0 5f 66 72 65 65 28 29 20 69 66 20 74 72 75 65 20 _free() if true
311b0 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42 79 */. int orderBy
311c0 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20 20 Consumed;
311d0 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70 75 /* True if outpu
311e0 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72 64 t is already ord
311f0 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 ered */. double
31200 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b 20 estimatedCost;
31210 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 65 /* Estimate
31220 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67 20 d cost of using
31230 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b this index */.};
31240 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
31250 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 INDEX_CONSTRAINT
31260 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69 6e 65 _EQ 2.#define
31270 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f SQLITE_INDEX_CO
31280 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20 20 34 NSTRAINT_GT 4
31290 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
312a0 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 INDEX_CONSTRAINT
312b0 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69 6e 65 _LE 8.#define
312c0 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f SQLITE_INDEX_CO
312d0 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 20 31 NSTRAINT_LT 1
312e0 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 6.#define SQLITE
312f0 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e _INDEX_CONSTRAIN
31300 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65 66 69 T_GE 32.#defi
31310 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f ne SQLITE_INDEX_
31320 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43 48 CONSTRAINT_MATCH
31330 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 64../*.** CAPI3
31340 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 REF: Register A
31350 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6d Virtual Table Im
31360 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 7b 48 31 plementation {H1
31370 38 32 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 8200} <S20400>.*
31380 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a * EXPERIMENTAL.*
31390 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
313a0 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 67 e is used to reg
313b0 69 73 74 65 72 20 61 20 6e 65 77 20 5b 76 69 72 ister a new [vir
313c0 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c tual table modul
313d0 65 5d 20 6e 61 6d 65 2e 0a 2a 2a 20 4d 6f 64 75 e] name..** Modu
313e0 6c 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 le names must be
313f0 20 72 65 67 69 73 74 65 72 65 64 20 62 65 66 6f registered befo
31400 72 65 0a 2a 2a 20 63 72 65 61 74 69 6e 67 20 61 re.** creating a
31410 20 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61 new [virtual ta
31420 62 6c 65 5d 20 75 73 69 6e 67 20 74 68 65 20 6d ble] using the m
31430 6f 64 75 6c 65 2c 20 6f 72 20 62 65 66 6f 72 65 odule, or before
31440 20 75 73 69 6e 67 20 61 0a 2a 2a 20 70 72 65 65 using a.** pree
31450 78 69 73 74 69 6e 67 20 5b 76 69 72 74 75 61 6c xisting [virtual
31460 20 74 61 62 6c 65 5d 20 66 6f 72 20 74 68 65 20 table] for the
31470 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 module..**.** Th
31480 65 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 69 73 e module name is
31490 20 72 65 67 69 73 74 65 72 65 64 20 6f 6e 20 74 registered on t
314a0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
314b0 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 nection] specifi
314c0 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 ed.** by the fir
314d0 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 st parameter. T
314e0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d he name of the m
314f0 6f 64 75 6c 65 20 69 73 20 67 69 76 65 6e 20 62 odule is given b
31500 79 20 74 68 65 20 0a 2a 2a 20 73 65 63 6f 6e 64 y the .** second
31510 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 parameter. The
31520 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
31530 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
31540 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e .** the implemen
31550 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 76 tation of the [v
31560 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 irtual table mod
31570 75 6c 65 5d 2e 20 20 20 54 68 65 20 66 6f 75 72 ule]. The four
31580 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 th.** parameter
31590 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 is an arbitrary
315a0 63 6c 69 65 6e 74 20 64 61 74 61 20 70 6f 69 6e client data poin
315b0 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73 73 ter that is pass
315c0 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a 20 69 6e ed through.** in
315d0 74 6f 20 74 68 65 20 5b 78 43 72 65 61 74 65 5d to the [xCreate]
315e0 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 and [xConnect]
315f0 6d 65 74 68 6f 64 73 20 6f 66 20 74 68 65 20 76 methods of the v
31600 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 irtual table mod
31610 75 6c 65 0a 2a 2a 20 77 68 65 6e 20 61 20 6e 65 ule.** when a ne
31620 77 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 w virtual table
31630 69 73 20 62 65 20 62 65 69 6e 67 20 63 72 65 61 is be being crea
31640 74 65 64 20 6f 72 20 72 65 69 6e 69 74 69 61 6c ted or reinitial
31650 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 ized..**.** This
31660 20 69 6e 74 65 72 66 61 63 65 20 68 61 73 20 65 interface has e
31670 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 xactly the same
31680 65 66 66 65 63 74 20 61 73 20 63 61 6c 6c 69 6e effect as callin
31690 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 g.** [sqlite3_cr
316a0 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 eate_module_v2()
316b0 5d 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 63 6c ] with a NULL cl
316c0 69 65 6e 74 20 64 61 74 61 20 64 65 73 74 72 75 ient data destru
316d0 63 74 6f 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f ctor..*/.SQLITE_
316e0 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 API SQLITE_EXPER
316f0 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 IMENTAL int sqli
31700 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c te3_create_modul
31710 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 e(. sqlite3 *db
31720 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
31730 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 /* SQLite connec
31740 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 tion to register
31750 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a module with */.
31760 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e const char *zN
31770 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 ame, /*
31780 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 Name of the modu
31790 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 le */. const sq
317a0 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c lite3_module *p,
317b0 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f /* Methods fo
317c0 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a r the module */.
317d0 20 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44 void *pClientD
317e0 61 74 61 20 20 20 20 20 20 20 20 20 20 2f 2a 20 ata /*
317f0 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 Client data for
31800 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 xCreate/xConnect
31810 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.);../*.** CA
31820 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 PI3REF: Register
31830 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 A Virtual Table
31840 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 Implementation
31850 7b 48 31 38 32 31 30 7d 20 3c 53 32 30 34 30 30 {H18210} <S20400
31860 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 >.** EXPERIMENTA
31870 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 L.**.** This rou
31880 74 69 6e 65 20 69 73 20 69 64 65 6e 74 69 63 61 tine is identica
31890 6c 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 l to the [sqlite
318a0 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 3_create_module(
318b0 29 5d 20 6d 65 74 68 6f 64 2c 0a 2a 2a 20 65 78 )] method,.** ex
318c0 63 65 70 74 20 74 68 61 74 20 69 74 20 68 61 73 cept that it has
318d0 20 61 6e 20 65 78 74 72 61 20 70 61 72 61 6d 65 an extra parame
318e0 74 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 0a ter to specify .
318f0 2a 2a 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 ** a destructor
31900 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 74 68 65 function for the
31910 20 63 6c 69 65 6e 74 20 64 61 74 61 20 70 6f 69 client data poi
31920 6e 74 65 72 2e 20 20 53 51 4c 69 74 65 20 77 69 nter. SQLite wi
31930 6c 6c 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 ll.** invoke the
31940 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 destructor func
31950 74 69 6f 6e 20 28 69 66 20 69 74 20 69 73 20 6e tion (if it is n
31960 6f 74 20 4e 55 4c 4c 29 20 77 68 65 6e 20 53 51 ot NULL) when SQ
31970 4c 69 74 65 0a 2a 2a 20 6e 6f 20 6c 6f 6e 67 65 Lite.** no longe
31980 72 20 6e 65 65 64 73 20 74 68 65 20 70 43 6c 69 r needs the pCli
31990 65 6e 74 44 61 74 61 20 70 6f 69 6e 74 65 72 2e entData pointer.
319a0 20 20 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 .*/.SQLITE_API
319b0 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 SQLITE_EXPERIME
319c0 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 NTAL int sqlite3
319d0 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 _create_module_v
319e0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2(. sqlite3 *db
319f0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
31a00 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 /* SQLite connec
31a10 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 tion to register
31a20 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a module with */.
31a30 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e const char *zN
31a40 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 ame, /*
31a50 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 Name of the modu
31a60 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 le */. const sq
31a70 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c lite3_module *p,
31a80 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f /* Methods fo
31a90 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a r the module */.
31aa0 20 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44 void *pClientD
31ab0 61 74 61 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 ata, /*
31ac0 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 Client data for
31ad0 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 xCreate/xConnect
31ae0 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 */. void(*xDes
31af0 74 72 6f 79 29 28 76 6f 69 64 2a 29 20 20 20 20 troy)(void*)
31b00 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73 74 72 /* Module destr
31b10 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 2a uctor function *
31b20 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.);../*.** CAPI
31b30 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 3REF: Virtual Ta
31b40 62 6c 65 20 49 6e 73 74 61 6e 63 65 20 4f 62 6a ble Instance Obj
31b50 65 63 74 20 7b 48 31 38 30 31 30 7d 20 3c 53 32 ect {H18010} <S2
31b60 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 0400>.** KEYWORD
31b70 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 0a S: sqlite3_vtab.
31b80 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a ** EXPERIMENTAL.
31b90 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 **.** Every [vir
31ba0 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c tual table modul
31bb0 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f e] implementatio
31bc0 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 n uses a subclas
31bd0 73 0a 2a 2a 20 6f 66 20 74 68 65 20 66 6f 6c 6c s.** of the foll
31be0 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 20 owing structure
31bf0 74 6f 20 64 65 73 63 72 69 62 65 20 61 20 70 61 to describe a pa
31c00 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 rticular instanc
31c10 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 76 69 72 e.** of the [vir
31c20 74 75 61 6c 20 74 61 62 6c 65 5d 2e 20 20 45 61 tual table]. Ea
31c30 63 68 20 73 75 62 63 6c 61 73 73 20 77 69 6c 6c ch subclass will
31c40 0a 2a 2a 20 62 65 20 74 61 69 6c 6f 72 65 64 20 .** be tailored
31c50 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 to the specific
31c60 6e 65 65 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 needs of the mod
31c70 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ule implementati
31c80 6f 6e 2e 0a 2a 2a 20 54 68 65 20 70 75 72 70 6f on..** The purpo
31c90 73 65 20 6f 66 20 74 68 69 73 20 73 75 70 65 72 se of this super
31ca0 63 6c 61 73 73 20 69 73 20 74 6f 20 64 65 66 69 class is to defi
31cb0 6e 65 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64 ne certain field
31cc0 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 63 6f s that are.** co
31cd0 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 mmon to all modu
31ce0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
31cf0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 ns..**.** Virtua
31d00 6c 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 73 l tables methods
31d10 20 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72 6f can set an erro
31d20 72 20 6d 65 73 73 61 67 65 20 62 79 20 61 73 73 r message by ass
31d30 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69 igning a.** stri
31d40 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ng obtained from
31d50 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 [sqlite3_mprint
31d60 66 28 29 5d 20 74 6f 20 7a 45 72 72 4d 73 67 2e f()] to zErrMsg.
31d70 20 20 54 68 65 20 6d 65 74 68 6f 64 20 73 68 6f The method sho
31d80 75 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 uld.** take care
31d90 20 74 68 61 74 20 61 6e 79 20 70 72 69 6f 72 20 that any prior
31da0 73 74 72 69 6e 67 20 69 73 20 66 72 65 65 64 20 string is freed
31db0 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 by a call to [sq
31dc0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a lite3_free()].**
31dd0 20 70 72 69 6f 72 20 74 6f 20 61 73 73 69 67 6e prior to assign
31de0 69 6e 67 20 61 20 6e 65 77 20 73 74 72 69 6e 67 ing a new string
31df0 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 41 66 to zErrMsg. Af
31e00 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 ter the error me
31e10 73 73 61 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69 ssage.** is deli
31e20 76 65 72 65 64 20 75 70 20 74 6f 20 74 68 65 20 vered up to the
31e30 63 6c 69 65 6e 74 20 61 70 70 6c 69 63 61 74 69 client applicati
31e40 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e 67 20 77 on, the string w
31e50 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 ill be automatic
31e60 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 20 62 79 ally.** freed by
31e70 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 sqlite3_free()
31e80 61 6e 64 20 74 68 65 20 7a 45 72 72 4d 73 67 20 and the zErrMsg
31e90 66 69 65 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65 field will be ze
31ea0 72 6f 65 64 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 roed..*/.struct
31eb0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 sqlite3_vtab {.
31ec0 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d const sqlite3_m
31ed0 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 odule *pModule;
31ee0 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 66 /* The module f
31ef0 6f 72 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 or this virtual
31f00 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e table */. int n
31f10 52 65 66 3b 20 20 20 20 20 20 20 20 20 20 20 20 Ref;
31f20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 4f /* NO
31f30 20 4c 4f 4e 47 45 52 20 55 53 45 44 20 2a 2f 0a LONGER USED */.
31f40 20 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b char *zErrMsg;
31f50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
31f60 20 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 61 /* Error messa
31f70 67 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ge from sqlite3_
31f80 6d 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f mprintf() */. /
31f90 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 * Virtual table
31fa0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
31fb0 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 will typically a
31fc0 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 dd additional fi
31fd0 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a elds */.};../*.*
31fe0 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 * CAPI3REF: Virt
31ff0 75 61 6c 20 54 61 62 6c 65 20 43 75 72 73 6f 72 ual Table Cursor
32000 20 4f 62 6a 65 63 74 20 20 7b 48 31 38 30 32 30 Object {H18020
32010 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 } <S20400>.** KE
32020 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f YWORDS: sqlite3_
32030 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 76 69 72 vtab_cursor {vir
32040 74 75 61 6c 20 74 61 62 6c 65 20 63 75 72 73 6f tual table curso
32050 72 7d 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 r}.** EXPERIMENT
32060 41 4c 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b AL.**.** Every [
32070 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f virtual table mo
32080 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 dule] implementa
32090 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 tion uses a subc
320a0 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 lass of the.** f
320b0 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 ollowing structu
320c0 72 65 20 74 6f 20 64 65 73 63 72 69 62 65 20 63 re to describe c
320d0 75 72 73 6f 72 73 20 74 68 61 74 20 70 6f 69 6e ursors that poin
320e0 74 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 76 t into the.** [v
320f0 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 61 6e irtual table] an
32100 64 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f d are used.** to
32110 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20 74 68 loop through th
32120 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e e virtual table.
32130 20 20 43 75 72 73 6f 72 73 20 61 72 65 20 63 72 Cursors are cr
32140 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 0a eated using the.
32150 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 ** [sqlite3_modu
32160 6c 65 2e 78 4f 70 65 6e 20 7c 20 78 4f 70 65 6e le.xOpen | xOpen
32170 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 ] method of the
32180 6d 6f 64 75 6c 65 20 61 6e 64 20 61 72 65 20 64 module and are d
32190 65 73 74 72 6f 79 65 64 0a 2a 2a 20 62 79 20 74 estroyed.** by t
321a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 he [sqlite3_modu
321b0 6c 65 2e 78 43 6c 6f 73 65 20 7c 20 78 43 6c 6f le.xClose | xClo
321c0 73 65 5d 20 6d 65 74 68 6f 64 2e 20 20 43 75 73 se] method. Cus
321d0 73 6f 72 73 20 61 72 65 20 75 73 65 64 0a 2a 2a sors are used.**
321e0 20 62 79 20 74 68 65 20 5b 78 46 69 6c 74 65 72 by the [xFilter
321f0 5d 2c 20 5b 78 4e 65 78 74 5d 2c 20 5b 78 45 6f ], [xNext], [xEo
32200 66 5d 2c 20 5b 78 43 6f 6c 75 6d 6e 5d 2c 20 61 f], [xColumn], a
32210 6e 64 20 5b 78 52 6f 77 69 64 5d 20 6d 65 74 68 nd [xRowid] meth
32220 6f 64 73 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 6f ods.** of the mo
32230 64 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64 75 dule. Each modu
32240 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
32250 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a n will define.**
32260 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 the content of
32270 61 20 63 75 72 73 6f 72 20 73 74 72 75 63 74 75 a cursor structu
32280 72 65 20 74 6f 20 73 75 69 74 20 69 74 73 20 6f re to suit its o
32290 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 wn needs..**.**
322a0 54 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 This superclass
322b0 65 78 69 73 74 73 20 69 6e 20 6f 72 64 65 72 20 exists in order
322c0 74 6f 20 64 65 66 69 6e 65 20 66 69 65 6c 64 73 to define fields
322d0 20 6f 66 20 74 68 65 20 63 75 72 73 6f 72 20 74 of the cursor t
322e0 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f hat.** are commo
322f0 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 n to all impleme
32300 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 ntations..*/.str
32310 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 uct sqlite3_vtab
32320 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69 _cursor {. sqli
32330 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 3b te3_vtab *pVtab;
32340 20 20 20 20 20 20 2f 2a 20 56 69 72 74 75 61 6c /* Virtual
32350 20 74 61 62 6c 65 20 6f 66 20 74 68 69 73 20 63 table of this c
32360 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 ursor */. /* Vi
32370 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c rtual table impl
32380 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c ementations will
32390 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 typically add a
323a0 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 dditional fields
323b0 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.};../*.** CA
323c0 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 20 PI3REF: Declare
323d0 54 68 65 20 53 63 68 65 6d 61 20 4f 66 20 41 20 The Schema Of A
323e0 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 7b 48 Virtual Table {H
323f0 31 38 32 38 30 7d 20 3c 53 32 30 34 30 30 3e 0a 18280} <S20400>.
32400 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a ** EXPERIMENTAL.
32410 2a 2a 0a 2a 2a 20 54 68 65 20 5b 78 43 72 65 61 **.** The [xCrea
32420 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 te] and [xConnec
32430 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 61 0a t] methods of a.
32440 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c ** [virtual tabl
32450 65 20 6d 6f 64 75 6c 65 5d 20 63 61 6c 6c 20 74 e module] call t
32460 68 69 73 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a his interface.**
32470 20 74 6f 20 64 65 63 6c 61 72 65 20 74 68 65 20 to declare the
32480 66 6f 72 6d 61 74 20 28 74 68 65 20 6e 61 6d 65 format (the name
32490 73 20 61 6e 64 20 64 61 74 61 74 79 70 65 73 20 s and datatypes
324a0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20 of the columns)
324b0 6f 66 0a 2a 2a 20 74 68 65 20 76 69 72 74 75 61 of.** the virtua
324c0 6c 20 74 61 62 6c 65 73 20 74 68 65 79 20 69 6d l tables they im
324d0 70 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 plement..*/.SQLI
324e0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 TE_API SQLITE_EX
324f0 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 PERIMENTAL int s
32500 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 qlite3_declare_v
32510 74 61 62 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f tab(sqlite3*, co
32520 6e 73 74 20 63 68 61 72 20 2a 7a 53 51 4c 29 3b nst char *zSQL);
32530 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
32540 3a 20 4f 76 65 72 6c 6f 61 64 20 41 20 46 75 6e : Overload A Fun
32550 63 74 69 6f 6e 20 46 6f 72 20 41 20 56 69 72 74 ction For A Virt
32560 75 61 6c 20 54 61 62 6c 65 20 7b 48 31 38 33 30 ual Table {H1830
32570 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 45 0} <S20400>.** E
32580 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a XPERIMENTAL.**.*
32590 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 * Virtual tables
325a0 20 63 61 6e 20 70 72 6f 76 69 64 65 20 61 6c 74 can provide alt
325b0 65 72 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d 65 ernative impleme
325c0 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63 ntations of func
325d0 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74 tions.** using t
325e0 68 65 20 5b 78 46 69 6e 64 46 75 6e 63 74 69 6f he [xFindFunctio
325f0 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 n] method of the
32600 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 [virtual table
32610 6d 6f 64 75 6c 65 5d 2e 20 20 0a 2a 2a 20 42 75 module]. .** Bu
32620 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e t global version
32630 73 20 6f 66 20 74 68 6f 73 65 20 66 75 6e 63 74 s of those funct
32640 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69 ions.** must exi
32650 73 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 62 st in order to b
32660 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a e overloaded..**
32670 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 6d 61 6b .** This API mak
32680 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61 6c es sure a global
32690 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 75 version of a fu
326a0 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70 61 nction with a pa
326b0 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65 rticular.** name
326c0 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 70 and number of p
326d0 61 72 61 6d 65 74 65 72 73 20 65 78 69 73 74 73 arameters exists
326e0 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66 75 . If no such fu
326f0 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a nction exists.**
32700 20 62 65 66 6f 72 65 20 74 68 69 73 20 41 50 49 before this API
32710 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65 is called, a ne
32720 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 72 w function is cr
32730 65 61 74 65 64 2e 20 20 54 68 65 20 69 6d 70 6c eated. The impl
32740 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 ementation.** of
32750 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f the new functio
32760 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65 73 20 n always causes
32770 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f 20 an exception to
32780 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a be thrown. So.*
32790 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 * the new functi
327a0 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20 66 on is not good f
327b0 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20 69 or anything by i
327c0 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c 79 tself. Its only
327d0 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20 74 .** purpose is t
327e0 6f 20 62 65 20 61 20 70 6c 61 63 65 68 6f 6c 64 o be a placehold
327f0 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 er function that
32800 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61 64 can be overload
32810 65 64 0a 2a 2a 20 62 79 20 61 20 5b 76 69 72 74 ed.** by a [virt
32820 75 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 53 ual table]..*/.S
32830 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
32840 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e _EXPERIMENTAL in
32850 74 20 73 71 6c 69 74 65 33 5f 6f 76 65 72 6c 6f t sqlite3_overlo
32860 61 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71 6c 69 ad_function(sqli
32870 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 te3*, const char
32880 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 *zFuncName, int
32890 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 nArg);../*.** T
328a0 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 he interface to
328b0 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c the virtual-tabl
328c0 65 20 6d 65 63 68 61 6e 69 73 6d 20 64 65 66 69 e mechanism defi
328d0 6e 65 64 20 61 62 6f 76 65 20 28 62 61 63 6b 20 ned above (back
328e0 75 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 up.** to a comme
328f0 6e 74 20 72 65 6d 61 72 6b 61 62 6c 79 20 73 69 nt remarkably si
32900 6d 69 6c 61 72 20 74 6f 20 74 68 69 73 20 6f 6e milar to this on
32910 65 29 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 e) is currently
32920 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f considered.** to
32930 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c be experimental
32940 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 . The interface
32950 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e might change in
32960 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 incompatible wa
32970 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 ys..** If this i
32980 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 s a problem for
32990 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 you, do not use
329a0 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 61 74 the interface at
329b0 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a this time..**.*
329c0 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72 74 75 * When the virtu
329d0 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 al-table mechani
329e0 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 sm stabilizes, w
329f0 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 e will declare t
32a00 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 he.** interface
32a10 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69 fixed, support i
32a20 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 t indefinitely,
32a30 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20 and remove this
32a40 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a comment..**.****
32a50 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 ** EXPERIMENTAL
32a60 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 - subject to cha
32a70 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 nge without noti
32a80 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ce *************
32a90 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 *.*/../*.** CAPI
32aa0 33 52 45 46 3a 20 41 20 48 61 6e 64 6c 65 20 54 3REF: A Handle T
32ab0 6f 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 20 7b o An Open BLOB {
32ac0 48 31 37 38 30 30 7d 20 3c 53 33 30 32 33 30 3e H17800} <S30230>
32ad0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 42 .** KEYWORDS: {B
32ae0 4c 4f 42 20 68 61 6e 64 6c 65 7d 20 7b 42 4c 4f LOB handle} {BLO
32af0 42 20 68 61 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a B handles}.**.**
32b00 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 An instance of
32b10 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 this object repr
32b20 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 42 esents an open B
32b30 4c 4f 42 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 LOB on which.**
32b40 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 [sqlite3_blob_op
32b50 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c en | incremental
32b60 20 42 4c 4f 42 20 49 2f 4f 5d 20 63 61 6e 20 62 BLOB I/O] can b
32b70 65 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 20 e performed..**
32b80 4f 62 6a 65 63 74 73 20 6f 66 20 74 68 69 73 20 Objects of this
32b90 74 79 70 65 20 61 72 65 20 63 72 65 61 74 65 64 type are created
32ba0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f by [sqlite3_blo
32bb0 62 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 b_open()].** and
32bc0 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 destroyed by [s
32bd0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 qlite3_blob_clos
32be0 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 e()]..** The [sq
32bf0 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 lite3_blob_read(
32c00 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
32c10 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 69 6e blob_write()] in
32c20 74 65 72 66 61 63 65 73 0a 2a 2a 20 63 61 6e 20 terfaces.** can
32c30 62 65 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 be used to read
32c40 6f 72 20 77 72 69 74 65 20 73 6d 61 6c 6c 20 73 or write small s
32c50 75 62 73 65 63 74 69 6f 6e 73 20 6f 66 20 74 68 ubsections of th
32c60 65 20 42 4c 4f 42 2e 0a 2a 2a 20 54 68 65 20 5b e BLOB..** The [
32c70 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 sqlite3_blob_byt
32c80 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 es()] interface
32c90 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 returns the size
32ca0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 69 6e 20 of the BLOB in
32cb0 62 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 bytes..*/.typede
32cc0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
32cd0 5f 62 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c _blob sqlite3_bl
32ce0 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 ob;../*.** CAPI3
32cf0 52 45 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 REF: Open A BLOB
32d00 20 46 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c For Incremental
32d10 20 49 2f 4f 20 7b 48 31 37 38 31 30 7d 20 3c 53 I/O {H17810} <S
32d20 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 30230>.**.** Thi
32d30 73 20 69 6e 74 65 72 66 61 63 65 73 20 6f 70 65 s interfaces ope
32d40 6e 73 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c ns a [BLOB handl
32d50 65 20 7c 20 68 61 6e 64 6c 65 5d 20 74 6f 20 74 e | handle] to t
32d60 68 65 20 42 4c 4f 42 20 6c 6f 63 61 74 65 64 0a he BLOB located.
32d70 2a 2a 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c 20 ** in row iRow,
32d80 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 column zColumn,
32d90 74 61 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 table zTable in
32da0 64 61 74 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a database zDb;.**
32db0 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c in other words,
32dc0 20 74 68 65 20 73 61 6d 65 20 42 4c 4f 42 20 74 the same BLOB t
32dd0 68 61 74 20 77 6f 75 6c 64 20 62 65 20 73 65 6c hat would be sel
32de0 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 ected by:.**.**
32df0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c <pre>.** SEL
32e00 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d ECT zColumn FROM
32e10 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 52 zDb.zTable WHER
32e20 45 20 5b 72 6f 77 69 64 5d 20 3d 20 69 52 6f 77 E [rowid] = iRow
32e30 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 20 7b 45 4e 44 ;.** </pre> {END
32e40 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 }.**.** If the f
32e50 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 69 lags parameter i
32e60 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e s non-zero, then
32e70 20 74 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 the BLOB is ope
32e80 6e 65 64 20 66 6f 72 20 72 65 61 64 0a 2a 2a 20 ned for read.**
32e90 61 6e 64 20 77 72 69 74 65 20 61 63 63 65 73 73 and write access
32ea0 2e 20 49 66 20 69 74 20 69 73 20 7a 65 72 6f 2c . If it is zero,
32eb0 20 74 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 the BLOB is ope
32ec0 6e 65 64 20 66 6f 72 20 72 65 61 64 20 61 63 63 ned for read acc
32ed0 65 73 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f ess..** It is no
32ee0 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 6f 70 t possible to op
32ef0 65 6e 20 61 20 63 6f 6c 75 6d 6e 20 74 68 61 74 en a column that
32f00 20 69 73 20 70 61 72 74 20 6f 66 20 61 6e 20 69 is part of an i
32f10 6e 64 65 78 20 6f 72 20 70 72 69 6d 61 72 79 20 ndex or primary
32f20 0a 2a 2a 20 6b 65 79 20 66 6f 72 20 77 72 69 74 .** key for writ
32f30 69 6e 67 2e 20 5e 49 66 20 5b 66 6f 72 65 69 67 ing. ^If [foreig
32f40 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 n key constraint
32f50 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64 2c 20 s] are enabled,
32f60 69 74 20 69 73 20 0a 2a 2a 20 6e 6f 74 20 70 6f it is .** not po
32f70 73 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61 ssible to open a
32f80 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 column that is
32f90 70 61 72 74 20 6f 66 20 61 20 5b 63 68 69 6c 64 part of a [child
32fa0 20 6b 65 79 5d 20 66 6f 72 20 77 72 69 74 69 6e key] for writin
32fb0 67 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 g..**.** Note th
32fc0 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 at the database
32fd0 6e 61 6d 65 20 69 73 20 6e 6f 74 20 74 68 65 20 name is not the
32fe0 66 69 6c 65 6e 61 6d 65 20 74 68 61 74 20 63 6f filename that co
32ff0 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 64 61 ntains.** the da
33000 74 61 62 61 73 65 20 62 75 74 20 72 61 74 68 65 tabase but rathe
33010 72 20 74 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e r the symbolic n
33020 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 ame of the datab
33030 61 73 65 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 ase that.** is a
33040 73 73 69 67 6e 65 64 20 77 68 65 6e 20 74 68 65 ssigned when the
33050 20 64 61 74 61 62 61 73 65 20 69 73 20 63 6f 6e database is con
33060 6e 65 63 74 65 64 20 75 73 69 6e 67 20 5b 41 54 nected using [AT
33070 54 41 43 48 5d 2e 0a 2a 2a 20 46 6f 72 20 74 68 TACH]..** For th
33080 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 e main database
33090 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 62 61 file, the databa
330a0 73 65 20 6e 61 6d 65 20 69 73 20 22 6d 61 69 6e se name is "main
330b0 22 2e 0a 2a 2a 20 46 6f 72 20 54 45 4d 50 20 74 "..** For TEMP t
330c0 61 62 6c 65 73 2c 20 74 68 65 20 64 61 74 61 62 ables, the datab
330d0 61 73 65 20 6e 61 6d 65 20 69 73 20 22 74 65 6d ase name is "tem
330e0 70 22 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 p"..**.** On suc
330f0 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b cess, [SQLITE_OK
33100 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e ] is returned an
33110 64 20 74 68 65 20 6e 65 77 20 5b 42 4c 4f 42 20 d the new [BLOB
33120 68 61 6e 64 6c 65 5d 20 69 73 20 77 72 69 74 74 handle] is writt
33130 65 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42 6c 6f 62 en.** to *ppBlob
33140 2e 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b . Otherwise an [
33150 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 error code] is r
33160 65 74 75 72 6e 65 64 20 61 6e 64 20 2a 70 70 42 eturned and *ppB
33170 6c 6f 62 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f lob is set.** to
33180 20 62 65 20 61 20 6e 75 6c 6c 20 70 6f 69 6e 74 be a null point
33190 65 72 2e 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 er..** This func
331a0 74 69 6f 6e 20 73 65 74 73 20 74 68 65 20 5b 64 tion sets the [d
331b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
331c0 6f 6e 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 61 on] error code a
331d0 6e 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20 61 63 nd message.** ac
331e0 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73 71 cessible via [sq
331f0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d lite3_errcode()]
33200 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 and [sqlite3_er
33210 72 6d 73 67 28 29 5d 20 61 6e 64 20 72 65 6c 61 rmsg()] and rela
33220 74 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 ted.** functions
33230 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 . Note that the
33240 20 2a 70 70 42 6c 6f 62 20 76 61 72 69 61 62 6c *ppBlob variabl
33250 65 20 69 73 20 61 6c 77 61 79 73 20 69 6e 69 74 e is always init
33260 69 61 6c 69 7a 65 64 20 69 6e 20 61 0a 2a 2a 20 ialized in a.**
33270 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20 69 way that makes i
33280 74 20 73 61 66 65 20 74 6f 20 69 6e 76 6f 6b 65 t safe to invoke
33290 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 [sqlite3_blob_c
332a0 6c 6f 73 65 28 29 5d 20 6f 6e 20 2a 70 70 42 6c lose()] on *ppBl
332b0 6f 62 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 ob.** regardless
332c0 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 20 of the success
332d0 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 or failure of th
332e0 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a 2a is routine..**.*
332f0 2a 20 49 66 20 74 68 65 20 72 6f 77 20 74 68 61 * If the row tha
33300 74 20 61 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 t a BLOB handle
33310 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 6d 6f 64 points to is mod
33320 69 66 69 65 64 20 62 79 20 61 6e 0a 2a 2a 20 5b ified by an.** [
33330 55 50 44 41 54 45 5d 2c 20 5b 44 45 4c 45 54 45 UPDATE], [DELETE
33340 5d 2c 20 6f 72 20 62 79 20 5b 4f 4e 20 43 4f 4e ], or by [ON CON
33350 46 4c 49 43 54 5d 20 73 69 64 65 2d 65 66 66 65 FLICT] side-effe
33360 63 74 73 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 cts.** then the
33370 42 4c 4f 42 20 68 61 6e 64 6c 65 20 69 73 20 6d BLOB handle is m
33380 61 72 6b 65 64 20 61 73 20 22 65 78 70 69 72 65 arked as "expire
33390 64 22 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 74 d"..** This is t
333a0 72 75 65 20 69 66 20 61 6e 79 20 63 6f 6c 75 6d rue if any colum
333b0 6e 20 6f 66 20 74 68 65 20 72 6f 77 20 69 73 20 n of the row is
333c0 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 61 20 changed, even a
333d0 63 6f 6c 75 6d 6e 0a 2a 2a 20 6f 74 68 65 72 20 column.** other
333e0 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 74 68 65 than the one the
333f0 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 69 73 20 BLOB handle is
33400 6f 70 65 6e 20 6f 6e 2e 0a 2a 2a 20 43 61 6c 6c open on..** Call
33410 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c s to [sqlite3_bl
33420 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 5b ob_read()] and [
33430 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 sqlite3_blob_wri
33440 74 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 61 20 65 te()] for.** a e
33450 78 70 69 72 65 64 20 42 4c 4f 42 20 68 61 6e 64 xpired BLOB hand
33460 6c 65 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 le fail with an
33470 72 65 74 75 72 6e 20 63 6f 64 65 20 6f 66 20 5b return code of [
33480 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a SQLITE_ABORT]..*
33490 2a 20 43 68 61 6e 67 65 73 20 77 72 69 74 74 65 * Changes writte
334a0 6e 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 70 72 n into a BLOB pr
334b0 69 6f 72 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 ior to the BLOB
334c0 65 78 70 69 72 69 6e 67 20 61 72 65 20 6e 6f 74 expiring are not
334d0 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 20 62 79 20 .** rollback by
334e0 74 68 65 20 65 78 70 69 72 61 74 69 6f 6e 20 6f the expiration o
334f0 66 20 74 68 65 20 42 4c 4f 42 2e 20 20 53 75 63 f the BLOB. Suc
33500 68 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 65 h changes will e
33510 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 63 6f 6d ventually.** com
33520 6d 69 74 20 69 66 20 74 68 65 20 74 72 61 6e 73 mit if the trans
33530 61 63 74 69 6f 6e 20 63 6f 6e 74 69 6e 75 65 73 action continues
33540 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a to completion..
33550 2a 2a 0a 2a 2a 20 55 73 65 20 74 68 65 20 5b 73 **.** Use the [s
33560 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 qlite3_blob_byte
33570 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 s()] interface t
33580 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 o determine the
33590 73 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f size of.** the o
335a0 70 65 6e 65 64 20 62 6c 6f 62 2e 20 20 54 68 65 pened blob. The
335b0 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62 20 size of a blob
335c0 6d 61 79 20 6e 6f 74 20 62 65 20 63 68 61 6e 67 may not be chang
335d0 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 69 6e ed by this.** in
335e0 74 65 72 66 61 63 65 2e 20 20 55 73 65 20 74 68 terface. Use th
335f0 65 20 5b 55 50 44 41 54 45 5d 20 53 51 4c 20 63 e [UPDATE] SQL c
33600 6f 6d 6d 61 6e 64 20 74 6f 20 63 68 61 6e 67 65 ommand to change
33610 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 0a 2a the size of a.*
33620 2a 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 54 68 * blob..**.** Th
33630 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f e [sqlite3_bind_
33640 7a 65 72 6f 62 6c 6f 62 28 29 5d 20 61 6e 64 20 zeroblob()] and
33650 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
33660 7a 65 72 6f 62 6c 6f 62 28 29 5d 20 69 6e 74 65 zeroblob()] inte
33670 72 66 61 63 65 73 0a 2a 2a 20 61 6e 64 20 74 68 rfaces.** and th
33680 65 20 62 75 69 6c 74 2d 69 6e 20 5b 7a 65 72 6f e built-in [zero
33690 62 6c 6f 62 5d 20 53 51 4c 20 66 75 6e 63 74 69 blob] SQL functi
336a0 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 on can be used,
336b0 69 66 20 64 65 73 69 72 65 64 2c 0a 2a 2a 20 74 if desired,.** t
336c0 6f 20 63 72 65 61 74 65 20 61 6e 20 65 6d 70 74 o create an empt
336d0 79 2c 20 7a 65 72 6f 2d 66 69 6c 6c 65 64 20 62 y, zero-filled b
336e0 6c 6f 62 20 69 6e 20 77 68 69 63 68 20 74 6f 20 lob in which to
336f0 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 75 73 read or write us
33700 69 6e 67 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 ing.** this inte
33710 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 6f 20 rface..**.** To
33720 61 76 6f 69 64 20 61 20 72 65 73 6f 75 72 63 65 avoid a resource
33730 20 6c 65 61 6b 2c 20 65 76 65 72 79 20 6f 70 65 leak, every ope
33740 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 n [BLOB handle]
33750 73 68 6f 75 6c 64 20 65 76 65 6e 74 75 61 6c 6c should eventuall
33760 79 0a 2a 2a 20 62 65 20 72 65 6c 65 61 73 65 64 y.** be released
33770 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 by a call to [s
33780 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 qlite3_blob_clos
33790 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 e()]..**.** Requ
337a0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 irements:.** [H1
337b0 37 38 31 33 5d 20 5b 48 31 37 38 31 34 5d 20 5b 7813] [H17814] [
337c0 48 31 37 38 31 36 5d 20 5b 48 31 37 38 31 39 5d H17816] [H17819]
337d0 20 5b 48 31 37 38 32 31 5d 20 5b 48 31 37 38 32 [H17821] [H1782
337e0 34 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 4].*/.SQLITE_API
337f0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f int sqlite3_blo
33800 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74 65 b_open(. sqlite
33810 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 3*,. const char
33820 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20 63 *zDb,. const c
33830 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 har *zTable,. c
33840 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 onst char *zColu
33850 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e mn,. sqlite3_in
33860 74 36 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74 20 t64 iRow,. int
33870 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69 74 65 33 flags,. sqlite3
33880 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 _blob **ppBlob.)
33890 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
338a0 46 3a 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20 F: Close A BLOB
338b0 48 61 6e 64 6c 65 20 7b 48 31 37 38 33 30 7d 20 Handle {H17830}
338c0 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 43 <S30230>.**.** C
338d0 6c 6f 73 65 73 20 61 6e 20 6f 70 65 6e 20 5b 42 loses an open [B
338e0 4c 4f 42 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a LOB handle]..**.
338f0 2a 2a 20 43 6c 6f 73 69 6e 67 20 61 20 42 4c 4f ** Closing a BLO
33900 42 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 B shall cause th
33910 65 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 e current transa
33920 63 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a ction to commit.
33930 2a 2a 20 69 66 20 74 68 65 72 65 20 61 72 65 20 ** if there are
33940 6e 6f 20 6f 74 68 65 72 20 42 4c 4f 42 73 2c 20 no other BLOBs,
33950 6e 6f 20 70 65 6e 64 69 6e 67 20 70 72 65 70 61 no pending prepa
33960 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 red statements,
33970 61 6e 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 and the.** datab
33980 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ase connection i
33990 73 20 69 6e 20 5b 61 75 74 6f 63 6f 6d 6d 69 74 s in [autocommit
339a0 20 6d 6f 64 65 5d 2e 0a 2a 2a 20 49 66 20 61 6e mode]..** If an
339b0 79 20 77 72 69 74 65 73 20 77 65 72 65 20 6d 61 y writes were ma
339c0 64 65 20 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20 de to the BLOB,
339d0 74 68 65 79 20 6d 69 67 68 74 20 62 65 20 68 65 they might be he
339e0 6c 64 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75 ld in cache.** u
339f0 6e 74 69 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f ntil the close o
33a00 70 65 72 61 74 69 6f 6e 20 69 66 20 74 68 65 79 peration if they
33a10 20 77 69 6c 6c 20 66 69 74 2e 0a 2a 2a 0a 2a 2a will fit..**.**
33a20 20 43 6c 6f 73 69 6e 67 20 74 68 65 20 42 4c 4f Closing the BLO
33a30 42 20 6f 66 74 65 6e 20 66 6f 72 63 65 73 20 74 B often forces t
33a40 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 75 he changes.** ou
33a50 74 20 74 6f 20 64 69 73 6b 20 61 6e 64 20 73 6f t to disk and so
33a60 20 69 66 20 61 6e 79 20 49 2f 4f 20 65 72 72 6f if any I/O erro
33a70 72 73 20 6f 63 63 75 72 2c 20 74 68 65 79 20 77 rs occur, they w
33a80 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63 63 75 72 ill likely occur
33a90 0a 2a 2a 20 61 74 20 74 68 65 20 74 69 6d 65 20 .** at the time
33aa0 77 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69 73 when the BLOB is
33ab0 20 63 6c 6f 73 65 64 2e 20 20 41 6e 79 20 65 72 closed. Any er
33ac0 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 rors that occur
33ad0 64 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73 69 6e during.** closin
33ae0 67 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 61 g are reported a
33af0 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 s a non-zero ret
33b00 75 72 6e 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a urn value..**.**
33b10 20 54 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f The BLOB is clo
33b20 73 65 64 20 75 6e 63 6f 6e 64 69 74 69 6f 6e 61 sed unconditiona
33b30 6c 6c 79 2e 20 20 45 76 65 6e 20 69 66 20 74 68 lly. Even if th
33b40 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 is routine retur
33b50 6e 73 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 63 ns.** an error c
33b60 6f 64 65 2c 20 74 68 65 20 42 4c 4f 42 20 69 73 ode, the BLOB is
33b70 20 73 74 69 6c 6c 20 63 6c 6f 73 65 64 2e 0a 2a still closed..*
33b80 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69 *.** Calling thi
33b90 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 s routine with a
33ba0 20 6e 75 6c 6c 20 70 6f 69 6e 74 65 72 20 28 77 null pointer (w
33bb0 68 69 63 68 20 61 73 20 77 6f 75 6c 64 20 62 65 hich as would be
33bc0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 returned.** by
33bd0 66 61 69 6c 65 64 20 63 61 6c 6c 20 74 6f 20 5b failed call to [
33be0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 sqlite3_blob_ope
33bf0 6e 28 29 5d 29 20 69 73 20 61 20 68 61 72 6d 6c n()]) is a harml
33c00 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a ess no-op..**.**
33c10 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
33c20 2a 20 5b 48 31 37 38 33 33 5d 20 5b 48 31 37 38 * [H17833] [H178
33c30 33 36 5d 20 5b 48 31 37 38 33 39 5d 0a 2a 2f 0a 36] [H17839].*/.
33c40 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
33c50 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 qlite3_blob_clos
33c60 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a e(sqlite3_blob *
33c70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
33c80 45 46 3a 20 52 65 74 75 72 6e 20 54 68 65 20 53 EF: Return The S
33c90 69 7a 65 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42 ize Of An Open B
33ca0 4c 4f 42 20 7b 48 31 37 38 34 30 7d 20 3c 53 33 LOB {H17840} <S3
33cb0 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 0230>.**.** Retu
33cc0 72 6e 73 20 74 68 65 20 73 69 7a 65 20 69 6e 20 rns the size in
33cd0 62 79 74 65 73 20 6f 66 20 74 68 65 20 42 4c 4f bytes of the BLO
33ce0 42 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 B accessible via
33cf0 20 74 68 65 20 0a 2a 2a 20 73 75 63 63 65 73 73 the .** success
33d00 66 75 6c 6c 79 20 6f 70 65 6e 65 64 20 5b 42 4c fully opened [BL
33d10 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 20 69 74 OB handle] in it
33d20 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e s only argument.
33d30 20 20 54 68 65 0a 2a 2a 20 69 6e 63 72 65 6d 65 The.** increme
33d40 6e 74 61 6c 20 62 6c 6f 62 20 49 2f 4f 20 72 6f ntal blob I/O ro
33d50 75 74 69 6e 65 73 20 63 61 6e 20 6f 6e 6c 79 20 utines can only
33d60 72 65 61 64 20 6f 72 20 6f 76 65 72 77 72 69 74 read or overwrit
33d70 69 6e 67 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 ing existing.**
33d80 62 6c 6f 62 20 63 6f 6e 74 65 6e 74 3b 20 74 68 blob content; th
33d90 65 79 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 ey cannot change
33da0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62 the size of a b
33db0 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 lob..**.** This
33dc0 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 routine only wor
33dd0 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 ks on a [BLOB ha
33de0 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 61 73 20 ndle] which has
33df0 62 65 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 been created.**
33e00 62 79 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 by a prior succe
33e10 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 ssful call to [s
33e20 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e qlite3_blob_open
33e30 28 29 5d 20 61 6e 64 20 77 68 69 63 68 20 68 61 ()] and which ha
33e40 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c s not.** been cl
33e50 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 osed by [sqlite3
33e60 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 _blob_close()].
33e70 20 50 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 Passing any oth
33e80 65 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a er pointer in.**
33e90 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 to this routine
33ea0 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 results in unde
33eb0 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 fined and probab
33ec0 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 ly undesirable b
33ed0 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 52 ehavior..**.** R
33ee0 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 equirements:.**
33ef0 5b 48 31 37 38 34 33 5d 0a 2a 2f 0a 53 51 4c 49 [H17843].*/.SQLI
33f00 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
33f10 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 73 71 e3_blob_bytes(sq
33f20 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a lite3_blob *);..
33f30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
33f40 52 65 61 64 20 44 61 74 61 20 46 72 6f 6d 20 41 Read Data From A
33f50 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 BLOB Incrementa
33f60 6c 6c 79 20 7b 48 31 37 38 35 30 7d 20 3c 53 33 lly {H17850} <S3
33f70 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 0230>.**.** This
33f80 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 function is use
33f90 64 20 74 6f 20 72 65 61 64 20 64 61 74 61 20 66 d to read data f
33fa0 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f rom an open [BLO
33fb0 42 20 68 61 6e 64 6c 65 5d 20 69 6e 74 6f 20 61 B handle] into a
33fc0 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70 6c .** caller-suppl
33fd0 69 65 64 20 62 75 66 66 65 72 2e 20 4e 20 62 79 ied buffer. N by
33fe0 74 65 73 20 6f 66 20 64 61 74 61 20 61 72 65 20 tes of data are
33ff0 63 6f 70 69 65 64 20 69 6e 74 6f 20 62 75 66 66 copied into buff
34000 65 72 20 5a 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 er Z.** from the
34010 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72 open BLOB, star
34020 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69 ting at offset i
34030 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 Offset..**.** If
34040 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 20 offset iOffset
34050 69 73 20 6c 65 73 73 20 74 68 61 6e 20 4e 20 62 is less than N b
34060 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20 65 6e ytes from the en
34070 64 20 6f 66 20 74 68 65 20 42 4c 4f 42 2c 0a 2a d of the BLOB,.*
34080 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d * [SQLITE_ERROR]
34090 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 is returned and
340a0 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61 64 no data is read
340b0 2e 20 20 49 66 20 4e 20 6f 72 20 69 4f 66 66 73 . If N or iOffs
340c0 65 74 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 et is.** less th
340d0 61 6e 20 7a 65 72 6f 2c 20 5b 53 51 4c 49 54 45 an zero, [SQLITE
340e0 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 _ERROR] is retur
340f0 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 ned and no data
34100 69 73 20 72 65 61 64 2e 0a 2a 2a 20 54 68 65 20 is read..** The
34110 73 69 7a 65 20 6f 66 20 74 68 65 20 62 6c 6f 62 size of the blob
34120 20 28 61 6e 64 20 68 65 6e 63 65 20 74 68 65 20 (and hence the
34130 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 maximum value of
34140 20 4e 2b 69 4f 66 66 73 65 74 29 0a 2a 2a 20 63 N+iOffset).** c
34150 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 an be determined
34160 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 using the [sqli
34170 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 te3_blob_bytes()
34180 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a ] interface..**.
34190 2a 2a 20 41 6e 20 61 74 74 65 6d 70 74 20 74 6f ** An attempt to
341a0 20 72 65 61 64 20 66 72 6f 6d 20 61 6e 20 65 78 read from an ex
341b0 70 69 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 pired [BLOB hand
341c0 6c 65 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61 le] fails with a
341d0 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 n.** error code
341e0 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 of [SQLITE_ABORT
341f0 5d 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 ]..**.** On succ
34200 65 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 ess, SQLITE_OK i
34210 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f s returned..** O
34220 74 68 65 72 77 69 73 65 2c 20 61 6e 20 5b 65 72 therwise, an [er
34230 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 ror code] or an
34240 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 [extended error
34250 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 code] is returne
34260 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f d..**.** This ro
34270 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 utine only works
34280 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 on a [BLOB hand
34290 6c 65 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 le] which has be
342a0 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 en created.** by
342b0 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 a prior success
342c0 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ful call to [sql
342d0 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 ite3_blob_open()
342e0 5d 20 61 6e 64 20 77 68 69 63 68 20 68 61 73 20 ] and which has
342f0 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 not.** been clos
34300 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 ed by [sqlite3_b
34310 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 lob_close()]. P
34320 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 assing any other
34330 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 pointer in.** t
34340 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 o this routine r
34350 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 esults in undefi
34360 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 ned and probably
34370 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 undesirable beh
34380 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 avior..**.** See
34390 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
343a0 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 2e 0a 2a blob_write()]..*
343b0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 *.** Requirement
343c0 73 3a 0a 2a 2a 20 5b 48 31 37 38 35 33 5d 20 5b s:.** [H17853] [
343d0 48 31 37 38 35 36 5d 20 5b 48 31 37 38 35 39 5d H17856] [H17859]
343e0 20 5b 48 31 37 38 36 32 5d 20 5b 48 31 37 38 36 [H17862] [H1786
343f0 33 5d 20 5b 48 31 37 38 36 35 5d 20 5b 48 31 37 3] [H17865] [H17
34400 38 36 38 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 868].*/.SQLITE_A
34410 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 PI int sqlite3_b
34420 6c 6f 62 5f 72 65 61 64 28 73 71 6c 69 74 65 33 lob_read(sqlite3
34430 5f 62 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 2a 5a _blob *, void *Z
34440 2c 20 69 6e 74 20 4e 2c 20 69 6e 74 20 69 4f 66 , int N, int iOf
34450 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 fset);../*.** CA
34460 50 49 33 52 45 46 3a 20 57 72 69 74 65 20 44 61 PI3REF: Write Da
34470 74 61 20 49 6e 74 6f 20 41 20 42 4c 4f 42 20 49 ta Into A BLOB I
34480 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 20 7b 48 31 ncrementally {H1
34490 37 38 37 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 7870} <S30230>.*
344a0 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 *.** This functi
344b0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 77 72 on is used to wr
344c0 69 74 65 20 64 61 74 61 20 69 6e 74 6f 20 61 6e ite data into an
344d0 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 open [BLOB hand
344e0 6c 65 5d 20 66 72 6f 6d 20 61 0a 2a 2a 20 63 61 le] from a.** ca
344f0 6c 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75 ller-supplied bu
34500 66 66 65 72 2e 20 4e 20 62 79 74 65 73 20 6f 66 ffer. N bytes of
34510 20 64 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 data are copied
34520 20 66 72 6f 6d 20 74 68 65 20 62 75 66 66 65 72 from the buffer
34530 20 5a 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 6f Z.** into the o
34540 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74 69 pen BLOB, starti
34550 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 ng at offset iOf
34560 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 fset..**.** If t
34570 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d he [BLOB handle]
34580 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 passed as the f
34590 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 77 61 irst argument wa
345a0 73 20 6e 6f 74 20 6f 70 65 6e 65 64 20 66 6f 72 s not opened for
345b0 0a 2a 2a 20 77 72 69 74 69 6e 67 20 28 74 68 65 .** writing (the
345c0 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 flags parameter
345d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f to [sqlite3_blo
345e0 62 5f 6f 70 65 6e 28 29 5d 20 77 61 73 20 7a 65 b_open()] was ze
345f0 72 6f 29 2c 0a 2a 2a 20 74 68 69 73 20 66 75 6e ro),.** this fun
34600 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 ction returns [S
34610 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e QLITE_READONLY].
34620 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 .**.** This func
34630 74 69 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f tion may only mo
34640 64 69 66 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 dify the content
34650 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 3b 20 69 s of the BLOB; i
34660 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 t is.** not poss
34670 69 62 6c 65 20 74 6f 20 69 6e 63 72 65 61 73 65 ible to increase
34680 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 42 the size of a B
34690 4c 4f 42 20 75 73 69 6e 67 20 74 68 69 73 20 41 LOB using this A
346a0 50 49 2e 0a 2a 2a 20 49 66 20 6f 66 66 73 65 74 PI..** If offset
346b0 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 iOffset is less
346c0 20 74 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72 than N bytes fr
346d0 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 om the end of th
346e0 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 e BLOB,.** [SQLI
346f0 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 TE_ERROR] is ret
34700 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 urned and no dat
34710 61 20 69 73 20 77 72 69 74 74 65 6e 2e 20 20 49 a is written. I
34720 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 f N is.** less t
34730 68 61 6e 20 7a 65 72 6f 20 5b 53 51 4c 49 54 45 han zero [SQLITE
34740 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 _ERROR] is retur
34750 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 ned and no data
34760 69 73 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 20 54 is written..** T
34770 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42 he size of the B
34780 4c 4f 42 20 28 61 6e 64 20 68 65 6e 63 65 20 74 LOB (and hence t
34790 68 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 he maximum value
347a0 20 6f 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a 2a of N+iOffset).*
347b0 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 * can be determi
347c0 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 73 ned using the [s
347d0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 qlite3_blob_byte
347e0 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a s()] interface..
347f0 2a 2a 0a 2a 2a 20 41 6e 20 61 74 74 65 6d 70 74 **.** An attempt
34800 20 74 6f 20 77 72 69 74 65 20 74 6f 20 61 6e 20 to write to an
34810 65 78 70 69 72 65 64 20 5b 42 4c 4f 42 20 68 61 expired [BLOB ha
34820 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77 69 74 68 ndle] fails with
34830 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 an.** error cod
34840 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f e of [SQLITE_ABO
34850 52 54 5d 2e 20 20 57 72 69 74 65 73 20 74 6f 20 RT]. Writes to
34860 74 68 65 20 42 4c 4f 42 20 74 68 61 74 20 6f 63 the BLOB that oc
34870 63 75 72 72 65 64 0a 2a 2a 20 62 65 66 6f 72 65 curred.** before
34880 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c the [BLOB handl
34890 65 5d 20 65 78 70 69 72 65 64 20 61 72 65 20 6e e] expired are n
348a0 6f 74 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 ot rolled back b
348b0 79 20 74 68 65 0a 2a 2a 20 65 78 70 69 72 61 74 y the.** expirat
348c0 69 6f 6e 20 6f 66 20 74 68 65 20 68 61 6e 64 6c ion of the handl
348d0 65 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 e, though of cou
348e0 72 73 65 20 74 68 6f 73 65 20 63 68 61 6e 67 65 rse those change
348f0 73 20 6d 69 67 68 74 0a 2a 2a 20 68 61 76 65 20 s might.** have
34900 62 65 65 6e 20 6f 76 65 72 77 72 69 74 74 65 6e been overwritten
34910 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e by the statemen
34920 74 20 74 68 61 74 20 65 78 70 69 72 65 64 20 74 t that expired t
34930 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 0a 2a he BLOB handle.*
34940 2a 20 6f 72 20 62 79 20 6f 74 68 65 72 20 69 6e * or by other in
34950 64 65 70 65 6e 64 65 6e 74 20 73 74 61 74 65 6d dependent statem
34960 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 ents..**.** On s
34970 75 63 63 65 73 73 2c 20 53 51 4c 49 54 45 5f 4f uccess, SQLITE_O
34980 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a K is returned..*
34990 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20 * Otherwise, an
349a0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 [error code] or
349b0 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 65 72 an [extended er
349c0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 ror code] is ret
349d0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 urned..**.** Thi
349e0 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 s routine only w
349f0 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 orks on a [BLOB
34a00 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 61 handle] which ha
34a10 73 20 62 65 65 6e 20 63 72 65 61 74 65 64 0a 2a s been created.*
34a20 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73 75 63 * by a prior suc
34a30 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 cessful call to
34a40 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 [sqlite3_blob_op
34a50 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 68 20 en()] and which
34a60 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 has not.** been
34a70 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 closed by [sqlit
34a80 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d e3_blob_close()]
34a90 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79 20 6f . Passing any o
34aa0 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a ther pointer in.
34ab0 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 ** to this routi
34ac0 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e ne results in un
34ad0 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 defined and prob
34ae0 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 ably undesirable
34af0 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a behavior..**.**
34b00 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
34b10 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d te3_blob_read()]
34b20 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d ..**.** Requirem
34b30 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 37 33 ents:.** [H17873
34b40 5d 20 5b 48 31 37 38 37 34 5d 20 5b 48 31 37 38 ] [H17874] [H178
34b50 37 35 5d 20 5b 48 31 37 38 37 36 5d 20 5b 48 31 75] [H17876] [H1
34b60 37 38 37 37 5d 20 5b 48 31 37 38 37 39 5d 20 5b 7877] [H17879] [
34b70 48 31 37 38 38 32 5d 20 5b 48 31 37 38 38 35 5d H17882] [H17885]
34b80 0a 2a 2a 20 5b 48 31 37 38 38 38 5d 0a 2a 2f 0a .** [H17888].*/.
34b90 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
34ba0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 qlite3_blob_writ
34bb0 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a e(sqlite3_blob *
34bc0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c , const void *z,
34bd0 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66 int n, int iOff
34be0 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 set);../*.** CAP
34bf0 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 46 I3REF: Virtual F
34c00 69 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a 65 63 ile System Objec
34c10 74 73 20 7b 48 31 31 32 30 30 7d 20 3c 53 32 30 ts {H11200} <S20
34c20 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 100>.**.** A vir
34c30 74 75 61 6c 20 66 69 6c 65 73 79 73 74 65 6d 20 tual filesystem
34c40 28 56 46 53 29 20 69 73 20 61 6e 20 5b 73 71 6c (VFS) is an [sql
34c50 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
34c60 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 .** that SQLite
34c70 75 73 65 73 20 74 6f 20 69 6e 74 65 72 61 63 74 uses to interact
34c80 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 75 6e 64 .** with the und
34c90 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e erlying operatin
34ca0 67 20 73 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20 g system. Most
34cb0 53 51 4c 69 74 65 20 62 75 69 6c 64 73 20 63 6f SQLite builds co
34cc0 6d 65 20 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e me with a.** sin
34cd0 67 6c 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 gle default VFS
34ce0 74 68 61 74 20 69 73 20 61 70 70 72 6f 70 72 69 that is appropri
34cf0 61 74 65 20 66 6f 72 20 74 68 65 20 68 6f 73 74 ate for the host
34d00 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 computer..** Ne
34d10 77 20 56 46 53 65 73 20 63 61 6e 20 62 65 20 72 w VFSes can be r
34d20 65 67 69 73 74 65 72 65 64 20 61 6e 64 20 65 78 egistered and ex
34d30 69 73 74 69 6e 67 20 56 46 53 65 73 20 63 61 6e isting VFSes can
34d40 20 62 65 20 75 6e 72 65 67 69 73 74 65 72 65 64 be unregistered
34d50 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 ..** The followi
34d60 6e 67 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 ng interfaces ar
34d70 65 20 70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a e provided..**.*
34d80 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66 * The sqlite3_vf
34d90 73 5f 66 69 6e 64 28 29 20 69 6e 74 65 72 66 61 s_find() interfa
34da0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 ce returns a poi
34db0 6e 74 65 72 20 74 6f 20 61 20 56 46 53 20 67 69 nter to a VFS gi
34dc0 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 0a 2a 2a ven its name..**
34dd0 20 4e 61 6d 65 73 20 61 72 65 20 63 61 73 65 20 Names are case
34de0 73 65 6e 73 69 74 69 76 65 2e 0a 2a 2a 20 4e 61 sensitive..** Na
34df0 6d 65 73 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 mes are zero-ter
34e00 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 minated UTF-8 st
34e10 72 69 6e 67 73 2e 0a 2a 2a 20 49 66 20 74 68 65 rings..** If the
34e20 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c 20 re is no match,
34e30 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 a NULL pointer i
34e40 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 s returned..** I
34e50 66 20 7a 56 66 73 4e 61 6d 65 20 69 73 20 4e 55 f zVfsName is NU
34e60 4c 4c 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 LL then the defa
34e70 75 6c 74 20 56 46 53 20 69 73 20 72 65 74 75 72 ult VFS is retur
34e80 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 56 ned..**.** New V
34e90 46 53 65 73 20 61 72 65 20 72 65 67 69 73 74 65 FSes are registe
34ea0 72 65 64 20 77 69 74 68 20 73 71 6c 69 74 65 33 red with sqlite3
34eb0 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 2e _vfs_register().
34ec0 0a 2a 2a 20 45 61 63 68 20 6e 65 77 20 56 46 53 .** Each new VFS
34ed0 20 62 65 63 6f 6d 65 73 20 74 68 65 20 64 65 66 becomes the def
34ee0 61 75 6c 74 20 56 46 53 20 69 66 20 74 68 65 20 ault VFS if the
34ef0 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 69 73 makeDflt flag is
34f00 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20 73 61 6d set..** The sam
34f10 65 20 56 46 53 20 63 61 6e 20 62 65 20 72 65 67 e VFS can be reg
34f20 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 istered multiple
34f30 20 74 69 6d 65 73 20 77 69 74 68 6f 75 74 20 69 times without i
34f40 6e 6a 75 72 79 2e 0a 2a 2a 20 54 6f 20 6d 61 6b njury..** To mak
34f50 65 20 61 6e 20 65 78 69 73 74 69 6e 67 20 56 46 e an existing VF
34f60 53 20 69 6e 74 6f 20 74 68 65 20 64 65 66 61 75 S into the defau
34f70 6c 74 20 56 46 53 2c 20 72 65 67 69 73 74 65 72 lt VFS, register
34f80 20 69 74 20 61 67 61 69 6e 0a 2a 2a 20 77 69 74 it again.** wit
34f90 68 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 h the makeDflt f
34fa0 6c 61 67 20 73 65 74 2e 20 20 49 66 20 74 77 6f lag set. If two
34fb0 20 64 69 66 66 65 72 65 6e 74 20 56 46 53 65 73 different VFSes
34fc0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 73 61 6d with the.** sam
34fd0 65 20 6e 61 6d 65 20 61 72 65 20 72 65 67 69 73 e name are regis
34fe0 74 65 72 65 64 2c 20 74 68 65 20 62 65 68 61 76 tered, the behav
34ff0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ior is undefined
35000 2e 20 20 49 66 20 61 0a 2a 2a 20 56 46 53 20 69 . If a.** VFS i
35010 73 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 s registered wit
35020 68 20 61 20 6e 61 6d 65 20 74 68 61 74 20 69 73 h a name that is
35030 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 NULL or an empt
35040 79 20 73 74 72 69 6e 67 2c 0a 2a 2a 20 74 68 65 y string,.** the
35050 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 n the behavior i
35060 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a s undefined..**.
35070 2a 2a 20 55 6e 72 65 67 69 73 74 65 72 20 61 20 ** Unregister a
35080 56 46 53 20 77 69 74 68 20 74 68 65 20 73 71 6c VFS with the sql
35090 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 ite3_vfs_unregis
350a0 74 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e ter() interface.
350b0 0a 2a 2a 20 49 66 20 74 68 65 20 64 65 66 61 75 .** If the defau
350c0 6c 74 20 56 46 53 20 69 73 20 75 6e 72 65 67 69 lt VFS is unregi
350d0 73 74 65 72 65 64 2c 20 61 6e 6f 74 68 65 72 20 stered, another
350e0 56 46 53 20 69 73 20 63 68 6f 73 65 6e 20 61 73 VFS is chosen as
350f0 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e .** the default.
35100 20 20 54 68 65 20 63 68 6f 69 63 65 20 66 6f 72 The choice for
35110 20 74 68 65 20 6e 65 77 20 56 46 53 20 69 73 20 the new VFS is
35120 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a arbitrary..**.**
35130 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a Requirements:.*
35140 2a 20 5b 48 31 31 32 30 33 5d 20 5b 48 31 31 32 * [H11203] [H112
35150 30 36 5d 20 5b 48 31 31 32 30 39 5d 20 5b 48 31 06] [H11209] [H1
35160 31 32 31 32 5d 20 5b 48 31 31 32 31 35 5d 20 5b 1212] [H11215] [
35170 48 31 31 32 31 38 5d 0a 2a 2f 0a 53 51 4c 49 54 H11218].*/.SQLIT
35180 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76 66 E_API sqlite3_vf
35190 73 20 2a 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 s *sqlite3_vfs_f
351a0 69 6e 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a ind(const char *
351b0 7a 56 66 73 4e 61 6d 65 29 3b 0a 53 51 4c 49 54 zVfsName);.SQLIT
351c0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
351d0 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 73 3_vfs_register(s
351e0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 qlite3_vfs*, int
351f0 20 6d 61 6b 65 44 66 6c 74 29 3b 0a 53 51 4c 49 makeDflt);.SQLI
35200 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
35210 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 e3_vfs_unregiste
35220 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b r(sqlite3_vfs*);
35230 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
35240 3a 20 4d 75 74 65 78 65 73 20 7b 48 31 37 30 30 : Mutexes {H1700
35250 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 0} <S20000>.**.*
35260 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 * The SQLite cor
35270 65 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 e uses these rou
35280 74 69 6e 65 73 20 66 6f 72 20 74 68 72 65 61 64 tines for thread
35290 0a 2a 2a 20 73 79 6e 63 68 72 6f 6e 69 7a 61 74 .** synchronizat
352a0 69 6f 6e 2e 20 54 68 6f 75 67 68 20 74 68 65 79 ion. Though they
352b0 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f are intended fo
352c0 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 r internal.** us
352d0 65 20 62 79 20 53 51 4c 69 74 65 2c 20 63 6f 64 e by SQLite, cod
352e0 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 e that links aga
352f0 69 6e 73 74 20 53 51 4c 69 74 65 20 69 73 0a 2a inst SQLite is.*
35300 2a 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 75 * permitted to u
35310 73 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 se any of these
35320 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 routines..**.**
35330 54 68 65 20 53 51 4c 69 74 65 20 73 6f 75 72 63 The SQLite sourc
35340 65 20 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20 e code contains
35350 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 multiple impleme
35360 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 6f 66 20 74 ntations.** of t
35370 68 65 73 65 20 6d 75 74 65 78 20 72 6f 75 74 69 hese mutex routi
35380 6e 65 73 2e 20 20 41 6e 20 61 70 70 72 6f 70 72 nes. An appropr
35390 69 61 74 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 iate implementat
353a0 69 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c 65 63 74 ion.** is select
353b0 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ed automatically
353c0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 at compile-time
353d0 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 . The following
353e0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
353f0 6f 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c ons are availabl
35400 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 e in the SQLite
35410 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e core:.**.** <ul>
35420 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 .** <li> SQLIT
35430 45 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c E_MUTEX_OS2.** <
35440 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 li> SQLITE_MUT
35450 45 58 5f 50 54 48 52 45 41 44 0a 2a 2a 20 3c 6c EX_PTHREAD.** <l
35460 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 i> SQLITE_MUTE
35470 58 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 X_W32.** <li>
35480 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f SQLITE_MUTEX_NOO
35490 50 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a P.** </ul>.**.**
354a0 20 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 The SQLITE_MUTE
354b0 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e 74 X_NOOP implement
354c0 61 74 69 6f 6e 20 69 73 20 61 20 73 65 74 20 6f ation is a set o
354d0 66 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 74 68 f routines.** th
354e0 61 74 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c 20 at does no real
354f0 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69 73 20 61 locking and is a
35500 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75 ppropriate for u
35510 73 65 20 69 6e 0a 2a 2a 20 61 20 73 69 6e 67 6c se in.** a singl
35520 65 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 e-threaded appli
35530 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 53 51 4c cation. The SQL
35540 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 2c 0a 2a ITE_MUTEX_OS2,.*
35550 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 * SQLITE_MUTEX_P
35560 54 48 52 45 41 44 2c 20 61 6e 64 20 53 51 4c 49 THREAD, and SQLI
35570 54 45 5f 4d 55 54 45 58 5f 57 33 32 20 69 6d 70 TE_MUTEX_W32 imp
35580 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 lementations.**
35590 61 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 are appropriate
355a0 66 6f 72 20 75 73 65 20 6f 6e 20 4f 53 2f 32 2c for use on OS/2,
355b0 20 55 6e 69 78 2c 20 61 6e 64 20 57 69 6e 64 6f Unix, and Windo
355c0 77 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 53 51 4c ws..**.** If SQL
355d0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
355e0 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f with the SQLITE_
355f0 4d 55 54 45 58 5f 41 50 50 44 45 46 20 70 72 65 MUTEX_APPDEF pre
35600 70 72 6f 63 65 73 73 6f 72 0a 2a 2a 20 6d 61 63 processor.** mac
35610 72 6f 20 64 65 66 69 6e 65 64 20 28 77 69 74 68 ro defined (with
35620 20 22 2d 44 53 51 4c 49 54 45 5f 4d 55 54 45 58 "-DSQLITE_MUTEX
35630 5f 41 50 50 44 45 46 3d 31 22 29 2c 20 74 68 65 _APPDEF=1"), the
35640 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20 69 6d n no mutex.** im
35650 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 plementation is
35660 69 6e 63 6c 75 64 65 64 20 77 69 74 68 20 74 68 included with th
35670 65 20 6c 69 62 72 61 72 79 2e 20 49 6e 20 74 68 e library. In th
35680 69 73 20 63 61 73 65 20 74 68 65 0a 2a 2a 20 61 is case the.** a
35690 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
356a0 73 75 70 70 6c 79 20 61 20 63 75 73 74 6f 6d 20 supply a custom
356b0 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 mutex implementa
356c0 74 69 6f 6e 20 75 73 69 6e 67 20 74 68 65 0a 2a tion using the.*
356d0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 * [SQLITE_CONFIG
356e0 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 20 6f _MUTEX] option o
356f0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f f the sqlite3_co
35700 6e 66 69 67 28 29 20 66 75 6e 63 74 69 6f 6e 0a nfig() function.
35710 2a 2a 20 62 65 66 6f 72 65 20 63 61 6c 6c 69 6e ** before callin
35720 67 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 g sqlite3_initia
35730 6c 69 7a 65 28 29 20 6f 72 20 61 6e 79 20 6f 74 lize() or any ot
35740 68 65 72 20 70 75 62 6c 69 63 20 73 71 6c 69 74 her public sqlit
35750 65 33 5f 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 e3_.** function
35760 74 68 61 74 20 63 61 6c 6c 73 20 73 71 6c 69 74 that calls sqlit
35770 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e e3_initialize().
35780 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 31 7d 20 .**.** {H17011}
35790 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 The sqlite3_mute
357a0 78 5f 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e x_alloc() routin
357b0 65 20 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65 e allocates a ne
357c0 77 0a 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20 72 w.** mutex and r
357d0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
357e0 20 74 6f 20 69 74 2e 20 7b 48 31 37 30 31 32 7d to it. {H17012}
357f0 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 4e If it returns N
35800 55 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d 65 61 6e ULL.** that mean
35810 73 20 74 68 61 74 20 61 20 6d 75 74 65 78 20 63 s that a mutex c
35820 6f 75 6c 64 20 6e 6f 74 20 62 65 20 61 6c 6c 6f ould not be allo
35830 63 61 74 65 64 2e 20 7b 48 31 37 30 31 33 7d 20 cated. {H17013}
35840 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 SQLite.** will u
35850 6e 77 69 6e 64 20 69 74 73 20 73 74 61 63 6b 20 nwind its stack
35860 61 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 65 72 and return an er
35870 72 6f 72 2e 20 7b 48 31 37 30 31 34 7d 20 54 68 ror. {H17014} Th
35880 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f e argument.** to
35890 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 sqlite3_mutex_a
358a0 6c 6c 6f 63 28 29 20 69 73 20 6f 6e 65 20 6f 66 lloc() is one of
358b0 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 these integer c
358c0 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20 onstants:.**.**
358d0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 <ul>.** <li> SQ
358e0 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a LITE_MUTEX_FAST.
358f0 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f ** <li> SQLITE_
35900 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a MUTEX_RECURSIVE.
35910 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f ** <li> SQLITE_
35920 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 MUTEX_STATIC_MAS
35930 54 45 52 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c TER.** <li> SQL
35940 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 ITE_MUTEX_STATIC
35950 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 _MEM.** <li> SQ
35960 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 LITE_MUTEX_STATI
35970 43 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c 69 3e 20 20 C_MEM2.** <li>
35980 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 SQLITE_MUTEX_STA
35990 54 49 43 5f 50 52 4e 47 0a 2a 2a 20 3c 6c 69 3e TIC_PRNG.** <li>
359a0 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 SQLITE_MUTEX_S
359b0 54 41 54 49 43 5f 4c 52 55 0a 2a 2a 20 3c 6c 69 TATIC_LRU.** <li
359c0 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f > SQLITE_MUTEX_
359d0 53 54 41 54 49 43 5f 4c 52 55 32 0a 2a 2a 20 3c STATIC_LRU2.** <
359e0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 /ul>.**.** {H170
359f0 31 35 7d 20 54 68 65 20 66 69 72 73 74 20 74 77 15} The first tw
35a00 6f 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 75 73 o constants caus
35a10 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f e sqlite3_mutex_
35a20 61 6c 6c 6f 63 28 29 20 74 6f 20 63 72 65 61 74 alloc() to creat
35a30 65 0a 2a 2a 20 61 20 6e 65 77 20 6d 75 74 65 78 e.** a new mutex
35a40 2e 20 20 54 68 65 20 6e 65 77 20 6d 75 74 65 78 . The new mutex
35a50 20 69 73 20 72 65 63 75 72 73 69 76 65 20 77 68 is recursive wh
35a60 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f en SQLITE_MUTEX_
35a70 52 45 43 55 52 53 49 56 45 0a 2a 2a 20 69 73 20 RECURSIVE.** is
35a80 75 73 65 64 20 62 75 74 20 6e 6f 74 20 6e 65 63 used but not nec
35a90 65 73 73 61 72 69 6c 79 20 73 6f 20 77 68 65 6e essarily so when
35aa0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 SQLITE_MUTEX_FA
35ab0 53 54 20 69 73 20 75 73 65 64 2e 20 7b 45 4e 44 ST is used. {END
35ac0 7d 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 69 }.** The mutex i
35ad0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f mplementation do
35ae0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d es not need to m
35af0 61 6b 65 20 61 20 64 69 73 74 69 6e 63 74 69 6f ake a distinctio
35b00 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c n.** between SQL
35b10 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 ITE_MUTEX_RECURS
35b20 49 56 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d IVE and SQLITE_M
35b30 55 54 45 58 5f 46 41 53 54 20 69 66 20 69 74 20 UTEX_FAST if it
35b40 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 does.** not want
35b50 20 74 6f 2e 20 20 7b 48 31 37 30 31 36 7d 20 42 to. {H17016} B
35b60 75 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f ut SQLite will o
35b70 6e 6c 79 20 72 65 71 75 65 73 74 20 61 20 72 65 nly request a re
35b80 63 75 72 73 69 76 65 20 6d 75 74 65 78 20 69 6e cursive mutex in
35b90 0a 2a 2a 20 63 61 73 65 73 20 77 68 65 72 65 20 .** cases where
35ba0 69 74 20 72 65 61 6c 6c 79 20 6e 65 65 64 73 20 it really needs
35bb0 6f 6e 65 2e 20 20 7b 45 4e 44 7d 20 49 66 20 61 one. {END} If a
35bc0 20 66 61 73 74 65 72 20 6e 6f 6e 2d 72 65 63 75 faster non-recu
35bd0 72 73 69 76 65 20 6d 75 74 65 78 0a 2a 2a 20 69 rsive mutex.** i
35be0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 mplementation is
35bf0 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74 68 available on th
35c00 65 20 68 6f 73 74 20 70 6c 61 74 66 6f 72 6d 2c e host platform,
35c10 20 74 68 65 20 6d 75 74 65 78 20 73 75 62 73 79 the mutex subsy
35c20 73 74 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 72 65 stem.** might re
35c30 74 75 72 6e 20 73 75 63 68 20 61 20 6d 75 74 65 turn such a mute
35c40 78 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f x in response to
35c50 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 SQLITE_MUTEX_FA
35c60 53 54 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 ST..**.** {H1701
35c70 37 7d 20 54 68 65 20 6f 74 68 65 72 20 61 6c 6c 7} The other all
35c80 6f 77 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 owed parameters
35c90 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 to sqlite3_mutex
35ca0 5f 61 6c 6c 6f 63 28 29 20 65 61 63 68 20 72 65 _alloc() each re
35cb0 74 75 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 turn.** a pointe
35cc0 72 20 74 6f 20 61 20 73 74 61 74 69 63 20 70 72 r to a static pr
35cd0 65 65 78 69 73 74 69 6e 67 20 6d 75 74 65 78 2e eexisting mutex.
35ce0 20 7b 45 4e 44 7d 20 20 53 69 78 20 73 74 61 74 {END} Six stat
35cf0 69 63 20 6d 75 74 65 78 65 73 20 61 72 65 0a 2a ic mutexes are.*
35d00 2a 20 75 73 65 64 20 62 79 20 74 68 65 20 63 75 * used by the cu
35d10 72 72 65 6e 74 20 76 65 72 73 69 6f 6e 20 6f 66 rrent version of
35d20 20 53 51 4c 69 74 65 2e 20 20 46 75 74 75 72 65 SQLite. Future
35d30 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
35d40 69 74 65 0a 2a 2a 20 6d 61 79 20 61 64 64 20 61 ite.** may add a
35d50 64 64 69 74 69 6f 6e 61 6c 20 73 74 61 74 69 63 dditional static
35d60 20 6d 75 74 65 78 65 73 2e 20 20 53 74 61 74 69 mutexes. Stati
35d70 63 20 6d 75 74 65 78 65 73 20 61 72 65 20 66 6f c mutexes are fo
35d80 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 r internal.** us
35d90 65 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 6c 79 e by SQLite only
35da0 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 . Applications
35db0 74 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 20 that use SQLite
35dc0 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 0a 2a mutexes should.*
35dd0 2a 20 75 73 65 20 6f 6e 6c 79 20 74 68 65 20 64 * use only the d
35de0 79 6e 61 6d 69 63 20 6d 75 74 65 78 65 73 20 72 ynamic mutexes r
35df0 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 49 54 eturned by SQLIT
35e00 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 6f 72 0a E_MUTEX_FAST or.
35e10 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f ** SQLITE_MUTEX_
35e20 52 45 43 55 52 53 49 56 45 2e 0a 2a 2a 0a 2a 2a RECURSIVE..**.**
35e30 20 7b 48 31 37 30 31 38 7d 20 4e 6f 74 65 20 74 {H17018} Note t
35e40 68 61 74 20 69 66 20 6f 6e 65 20 6f 66 20 74 68 hat if one of th
35e50 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 e dynamic mutex
35e60 70 61 72 61 6d 65 74 65 72 73 20 28 53 51 4c 49 parameters (SQLI
35e70 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a TE_MUTEX_FAST.**
35e80 20 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 or SQLITE_MUTEX
35e90 5f 52 45 43 55 52 53 49 56 45 29 20 69 73 20 75 _RECURSIVE) is u
35ea0 73 65 64 20 74 68 65 6e 20 73 71 6c 69 74 65 33 sed then sqlite3
35eb0 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a _mutex_alloc().*
35ec0 2a 20 72 65 74 75 72 6e 73 20 61 20 64 69 66 66 * returns a diff
35ed0 65 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65 erent mutex on e
35ee0 76 65 72 79 20 63 61 6c 6c 2e 20 20 7b 48 31 37 very call. {H17
35ef0 30 33 34 7d 20 42 75 74 20 66 6f 72 20 74 68 65 034} But for the
35f00 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 static.** mutex
35f10 20 74 79 70 65 73 2c 20 74 68 65 20 73 61 6d 65 types, the same
35f20 20 6d 75 74 65 78 20 69 73 20 72 65 74 75 72 6e mutex is return
35f30 65 64 20 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c ed on every call
35f40 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 74 68 65 that has.** the
35f50 20 73 61 6d 65 20 74 79 70 65 20 6e 75 6d 62 65 same type numbe
35f60 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 39 r..**.** {H17019
35f70 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 } The sqlite3_mu
35f80 74 65 78 5f 66 72 65 65 28 29 20 72 6f 75 74 69 tex_free() routi
35f90 6e 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 ne deallocates a
35fa0 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61 previously.** a
35fb0 6c 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d 69 63 llocated dynamic
35fc0 20 6d 75 74 65 78 2e 20 7b 48 31 37 30 32 30 7d mutex. {H17020}
35fd0 20 53 51 4c 69 74 65 20 69 73 20 63 61 72 65 66 SQLite is caref
35fe0 75 6c 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 ul to deallocate
35ff0 20 65 76 65 72 79 0a 2a 2a 20 64 79 6e 61 6d 69 every.** dynami
36000 63 20 6d 75 74 65 78 20 74 68 61 74 20 69 74 20 c mutex that it
36010 61 6c 6c 6f 63 61 74 65 73 2e 20 7b 41 31 37 30 allocates. {A170
36020 32 31 7d 20 54 68 65 20 64 79 6e 61 6d 69 63 20 21} The dynamic
36030 6d 75 74 65 78 65 73 20 6d 75 73 74 20 6e 6f 74 mutexes must not
36040 20 62 65 20 69 6e 0a 2a 2a 20 75 73 65 20 77 68 be in.** use wh
36050 65 6e 20 74 68 65 79 20 61 72 65 20 64 65 61 6c en they are deal
36060 6c 6f 63 61 74 65 64 2e 20 7b 41 31 37 30 32 32 located. {A17022
36070 7d 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 } Attempting to
36080 64 65 61 6c 6c 6f 63 61 74 65 20 61 20 73 74 61 deallocate a sta
36090 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20 72 65 73 tic.** mutex res
360a0 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 ults in undefine
360b0 64 20 62 65 68 61 76 69 6f 72 2e 20 7b 48 31 37 d behavior. {H17
360c0 30 32 33 7d 20 53 51 4c 69 74 65 20 6e 65 76 65 023} SQLite neve
360d0 72 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a 2a 2a r deallocates.**
360e0 20 61 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e a static mutex.
360f0 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 {END}.**.** The
36100 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 sqlite3_mutex_e
36110 6e 74 65 72 28 29 20 61 6e 64 20 73 71 6c 69 74 nter() and sqlit
36120 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 72 e3_mutex_try() r
36130 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 0a outines attempt.
36140 2a 2a 20 74 6f 20 65 6e 74 65 72 20 61 20 6d 75 ** to enter a mu
36150 74 65 78 2e 20 7b 48 31 37 30 32 34 7d 20 49 66 tex. {H17024} If
36160 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 another thread
36170 69 73 20 61 6c 72 65 61 64 79 20 77 69 74 68 69 is already withi
36180 6e 20 74 68 65 20 6d 75 74 65 78 2c 0a 2a 2a 20 n the mutex,.**
36190 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e sqlite3_mutex_en
361a0 74 65 72 28 29 20 77 69 6c 6c 20 62 6c 6f 63 6b ter() will block
361b0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 and sqlite3_mut
361c0 65 78 5f 74 72 79 28 29 20 77 69 6c 6c 20 72 65 ex_try() will re
361d0 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 turn.** SQLITE_B
361e0 55 53 59 2e 20 7b 48 31 37 30 32 35 7d 20 20 54 USY. {H17025} T
361f0 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 he sqlite3_mutex
36200 5f 74 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 _try() interface
36210 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
36220 5f 4f 4b 5d 0a 2a 2a 20 75 70 6f 6e 20 73 75 63 _OK].** upon suc
36230 63 65 73 73 66 75 6c 20 65 6e 74 72 79 2e 20 20 cessful entry.
36240 7b 48 31 37 30 32 36 7d 20 4d 75 74 65 78 65 73 {H17026} Mutexes
36250 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a created using.*
36260 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 * SQLITE_MUTEX_R
36270 45 43 55 52 53 49 56 45 20 63 61 6e 20 62 65 20 ECURSIVE can be
36280 65 6e 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 entered multiple
36290 20 74 69 6d 65 73 20 62 79 20 74 68 65 20 73 61 times by the sa
362a0 6d 65 20 74 68 72 65 61 64 2e 0a 2a 2a 20 7b 48 me thread..** {H
362b0 31 37 30 32 37 7d 20 49 6e 20 73 75 63 68 20 63 17027} In such c
362c0 61 73 65 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 74 ases the,.** mut
362d0 65 78 20 6d 75 73 74 20 62 65 20 65 78 69 74 65 ex must be exite
362e0 64 20 61 6e 20 65 71 75 61 6c 20 6e 75 6d 62 65 d an equal numbe
362f0 72 20 6f 66 20 74 69 6d 65 73 20 62 65 66 6f 72 r of times befor
36300 65 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 e another thread
36310 0a 2a 2a 20 63 61 6e 20 65 6e 74 65 72 2e 20 20 .** can enter.
36320 7b 41 31 37 30 32 38 7d 20 49 66 20 74 68 65 20 {A17028} If the
36330 73 61 6d 65 20 74 68 72 65 61 64 20 74 72 69 65 same thread trie
36340 73 20 74 6f 20 65 6e 74 65 72 20 61 6e 79 20 6f s to enter any o
36350 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 ther.** kind of
36360 6d 75 74 65 78 20 6d 6f 72 65 20 74 68 61 6e 20 mutex more than
36370 6f 6e 63 65 2c 20 74 68 65 20 62 65 68 61 76 69 once, the behavi
36380 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e or is undefined.
36390 0a 2a 2a 20 7b 48 31 37 30 32 39 7d 20 53 51 4c .** {H17029} SQL
363a0 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 65 ite will never e
363b0 78 68 69 62 69 74 0a 2a 2a 20 73 75 63 68 20 62 xhibit.** such b
363c0 65 68 61 76 69 6f 72 20 69 6e 20 69 74 73 20 6f ehavior in its o
363d0 77 6e 20 75 73 65 20 6f 66 20 6d 75 74 65 78 65 wn use of mutexe
363e0 73 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 73 79 s..**.** Some sy
363f0 73 74 65 6d 73 20 28 66 6f 72 20 65 78 61 6d 70 stems (for examp
36400 6c 65 2c 20 57 69 6e 64 6f 77 73 20 39 35 29 20 le, Windows 95)
36410 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 74 do not support t
36420 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 he operation.**
36430 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 73 implemented by s
36440 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 qlite3_mutex_try
36450 28 29 2e 20 20 4f 6e 20 74 68 6f 73 65 20 73 79 (). On those sy
36460 73 74 65 6d 73 2c 20 73 71 6c 69 74 65 33 5f 6d stems, sqlite3_m
36470 75 74 65 78 5f 74 72 79 28 29 0a 2a 2a 20 77 69 utex_try().** wi
36480 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e ll always return
36490 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 7b SQLITE_BUSY. {
364a0 48 31 37 30 33 30 7d 20 54 68 65 20 53 51 4c 69 H17030} The SQLi
364b0 74 65 20 63 6f 72 65 20 6f 6e 6c 79 20 65 76 65 te core only eve
364c0 72 20 75 73 65 73 0a 2a 2a 20 73 71 6c 69 74 65 r uses.** sqlite
364d0 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 61 73 3_mutex_try() as
364e0 20 61 6e 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e an optimization
364f0 20 73 6f 20 74 68 69 73 20 69 73 20 61 63 63 65 so this is acce
36500 70 74 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e ptable behavior.
36510 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 33 31 7d 20 .**.** {H17031}
36520 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 The sqlite3_mute
36530 78 5f 6c 65 61 76 65 28 29 20 72 6f 75 74 69 6e x_leave() routin
36540 65 20 65 78 69 74 73 20 61 20 6d 75 74 65 78 20 e exits a mutex
36550 74 68 61 74 20 77 61 73 0a 2a 2a 20 70 72 65 76 that was.** prev
36560 69 6f 75 73 6c 79 20 65 6e 74 65 72 65 64 20 62 iously entered b
36570 79 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 y the same threa
36580 64 2e 20 20 7b 41 31 37 30 33 32 7d 20 54 68 65 d. {A17032} The
36590 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 behavior.** is
365a0 75 6e 64 65 66 69 6e 65 64 20 69 66 20 74 68 65 undefined if the
365b0 20 6d 75 74 65 78 20 69 73 20 6e 6f 74 20 63 75 mutex is not cu
365c0 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 rrently entered
365d0 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e by the.** callin
365e0 67 20 74 68 72 65 61 64 20 6f 72 20 69 73 20 6e g thread or is n
365f0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c ot currently all
36600 6f 63 61 74 65 64 2e 20 20 7b 48 31 37 30 33 33 ocated. {H17033
36610 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a } SQLite will.**
36620 20 6e 65 76 65 72 20 64 6f 20 65 69 74 68 65 72 never do either
36630 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 . {END}.**.** If
36640 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f the argument to
36650 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 sqlite3_mutex_e
36660 6e 74 65 72 28 29 2c 20 73 71 6c 69 74 65 33 5f nter(), sqlite3_
36670 6d 75 74 65 78 5f 74 72 79 28 29 2c 20 6f 72 0a mutex_try(), or.
36680 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 ** sqlite3_mutex
36690 5f 6c 65 61 76 65 28 29 20 69 73 20 61 20 4e 55 _leave() is a NU
366a0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e LL pointer, then
366b0 20 61 6c 6c 20 74 68 72 65 65 20 72 6f 75 74 69 all three routi
366c0 6e 65 73 0a 2a 2a 20 62 65 68 61 76 65 20 61 73 nes.** behave as
366d0 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 53 no-ops..**.** S
366e0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
366f0 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 3_mutex_held()]
36700 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 and [sqlite3_mut
36710 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a 2a ex_notheld()]..*
36720 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c /.SQLITE_API sql
36730 69 74 65 33 5f 6d 75 74 65 78 20 2a 73 71 6c 69 ite3_mutex *sqli
36740 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 te3_mutex_alloc(
36750 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 int);.SQLITE_API
36760 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 void sqlite3_mu
36770 74 65 78 5f 66 72 65 65 28 73 71 6c 69 74 65 33 tex_free(sqlite3
36780 5f 6d 75 74 65 78 2a 29 3b 0a 53 51 4c 49 54 45 _mutex*);.SQLITE
36790 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 _API void sqlite
367a0 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 73 71 3_mutex_enter(sq
367b0 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 53 lite3_mutex*);.S
367c0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
367d0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 lite3_mutex_try(
367e0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b sqlite3_mutex*);
367f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
36800 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c sqlite3_mutex_l
36810 65 61 76 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 eave(sqlite3_mut
36820 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ex*);../*.** CAP
36830 49 33 52 45 46 3a 20 4d 75 74 65 78 20 4d 65 74 I3REF: Mutex Met
36840 68 6f 64 73 20 4f 62 6a 65 63 74 20 7b 48 31 37 hods Object {H17
36850 31 32 30 7d 20 3c 53 32 30 31 33 30 3e 0a 2a 2a 120} <S20130>.**
36860 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a EXPERIMENTAL.**
36870 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 .** An instance
36880 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 of this structur
36890 65 20 64 65 66 69 6e 65 73 20 74 68 65 20 6c 6f e defines the lo
368a0 77 2d 6c 65 76 65 6c 20 72 6f 75 74 69 6e 65 73 w-level routines
368b0 0a 2a 2a 20 75 73 65 64 20 74 6f 20 61 6c 6c 6f .** used to allo
368c0 63 61 74 65 20 61 6e 64 20 75 73 65 20 6d 75 74 cate and use mut
368d0 65 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 55 73 75 61 exes..**.** Usua
368e0 6c 6c 79 2c 20 74 68 65 20 64 65 66 61 75 6c 74 lly, the default
368f0 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 mutex implement
36900 61 74 69 6f 6e 73 20 70 72 6f 76 69 64 65 64 20 ations provided
36910 62 79 20 53 51 4c 69 74 65 20 61 72 65 0a 2a 2a by SQLite are.**
36920 20 73 75 66 66 69 63 69 65 6e 74 2c 20 68 6f 77 sufficient, how
36930 65 76 65 72 20 74 68 65 20 75 73 65 72 20 68 61 ever the user ha
36940 73 20 74 68 65 20 6f 70 74 69 6f 6e 20 6f 66 20 s the option of
36950 73 75 62 73 74 69 74 75 74 69 6e 67 20 61 20 63 substituting a c
36960 75 73 74 6f 6d 0a 2a 2a 20 69 6d 70 6c 65 6d 65 ustom.** impleme
36970 6e 74 61 74 69 6f 6e 20 66 6f 72 20 73 70 65 63 ntation for spec
36980 69 61 6c 69 7a 65 64 20 64 65 70 6c 6f 79 6d 65 ialized deployme
36990 6e 74 73 20 6f 72 20 73 79 73 74 65 6d 73 20 66 nts or systems f
369a0 6f 72 20 77 68 69 63 68 20 53 51 4c 69 74 65 0a or which SQLite.
369b0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 ** does not prov
369c0 69 64 65 20 61 20 73 75 69 74 61 62 6c 65 20 69 ide a suitable i
369d0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 49 mplementation. I
369e0 6e 20 74 68 69 73 20 63 61 73 65 2c 20 74 68 65 n this case, the
369f0 20 75 73 65 72 0a 2a 2a 20 63 72 65 61 74 65 73 user.** creates
36a00 20 61 6e 64 20 70 6f 70 75 6c 61 74 65 73 20 61 and populates a
36a10 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
36a20 69 73 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 is structure to
36a30 70 61 73 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 pass.** to sqlit
36a40 65 33 5f 63 6f 6e 66 69 67 28 29 20 61 6c 6f 6e e3_config() alon
36a50 67 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 g with the [SQLI
36a60 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d TE_CONFIG_MUTEX]
36a70 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 64 64 69 option..** Addi
36a80 74 69 6f 6e 61 6c 6c 79 2c 20 61 6e 20 69 6e 73 tionally, an ins
36a90 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 tance of this st
36aa0 72 75 63 74 75 72 65 20 63 61 6e 20 62 65 20 75 ructure can be u
36ab0 73 65 64 20 61 73 20 61 6e 0a 2a 2a 20 6f 75 74 sed as an.** out
36ac0 70 75 74 20 76 61 72 69 61 62 6c 65 20 77 68 65 put variable whe
36ad0 6e 20 71 75 65 72 79 69 6e 67 20 74 68 65 20 73 n querying the s
36ae0 79 73 74 65 6d 20 66 6f 72 20 74 68 65 20 63 75 ystem for the cu
36af0 72 72 65 6e 74 20 6d 75 74 65 78 0a 2a 2a 20 69 rrent mutex.** i
36b00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 75 mplementation, u
36b10 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 sing the [SQLITE
36b20 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 _CONFIG_GETMUTEX
36b30 5d 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 ] option..**.**
36b40 54 68 65 20 78 4d 75 74 65 78 49 6e 69 74 20 6d The xMutexInit m
36b50 65 74 68 6f 64 20 64 65 66 69 6e 65 64 20 62 79 ethod defined by
36b60 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 this structure
36b70 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a is invoked as.**
36b80 20 70 61 72 74 20 6f 66 20 73 79 73 74 65 6d 20 part of system
36b90 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 62 initialization b
36ba0 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e y the sqlite3_in
36bb0 69 74 69 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 itialize() funct
36bc0 69 6f 6e 2e 0a 2a 2a 20 7b 48 31 37 30 30 31 7d ion..** {H17001}
36bd0 20 54 68 65 20 78 4d 75 74 65 78 49 6e 69 74 20 The xMutexInit
36be0 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 62 65 routine shall be
36bf0 20 63 61 6c 6c 65 64 20 62 79 20 53 51 4c 69 74 called by SQLit
36c00 65 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 0a e once for each.
36c10 2a 2a 20 65 66 66 65 63 74 69 76 65 20 63 61 6c ** effective cal
36c20 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 69 6e l to [sqlite3_in
36c30 69 74 69 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a itialize()]..**.
36c40 2a 2a 20 54 68 65 20 78 4d 75 74 65 78 45 6e 64 ** The xMutexEnd
36c50 20 6d 65 74 68 6f 64 20 64 65 66 69 6e 65 64 20 method defined
36c60 62 79 20 74 68 69 73 20 73 74 72 75 63 74 75 72 by this structur
36c70 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 0a e is invoked as.
36c80 2a 2a 20 70 61 72 74 20 6f 66 20 73 79 73 74 65 ** part of syste
36c90 6d 20 73 68 75 74 64 6f 77 6e 20 62 79 20 74 68 m shutdown by th
36ca0 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f e sqlite3_shutdo
36cb0 77 6e 28 29 20 66 75 6e 63 74 69 6f 6e 2e 20 54 wn() function. T
36cc0 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 he.** implementa
36cd0 74 69 6f 6e 20 6f 66 20 74 68 69 73 20 6d 65 74 tion of this met
36ce0 68 6f 64 20 69 73 20 65 78 70 65 63 74 65 64 20 hod is expected
36cf0 74 6f 20 72 65 6c 65 61 73 65 20 61 6c 6c 20 6f to release all o
36d00 75 74 73 74 61 6e 64 69 6e 67 0a 2a 2a 20 72 65 utstanding.** re
36d10 73 6f 75 72 63 65 73 20 6f 62 74 61 69 6e 65 64 sources obtained
36d20 20 62 79 20 74 68 65 20 6d 75 74 65 78 20 6d 65 by the mutex me
36d30 74 68 6f 64 73 20 69 6d 70 6c 65 6d 65 6e 74 61 thods implementa
36d40 74 69 6f 6e 2c 20 65 73 70 65 63 69 61 6c 6c 79 tion, especially
36d50 0a 2a 2a 20 74 68 6f 73 65 20 6f 62 74 61 69 6e .** those obtain
36d60 65 64 20 62 79 20 74 68 65 20 78 4d 75 74 65 78 ed by the xMutex
36d70 49 6e 69 74 20 6d 65 74 68 6f 64 2e 20 7b 48 31 Init method. {H1
36d80 37 30 30 33 7d 20 54 68 65 20 78 4d 75 74 65 78 7003} The xMutex
36d90 45 6e 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 End().** interfa
36da0 63 65 20 73 68 61 6c 6c 20 62 65 20 69 6e 76 6f ce shall be invo
36db0 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 ked once for eac
36dc0 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 h call to [sqlit
36dd0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a e3_shutdown()]..
36de0 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e **.** The remain
36df0 69 6e 67 20 73 65 76 65 6e 20 6d 65 74 68 6f 64 ing seven method
36e00 73 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 s defined by thi
36e10 73 20 73 74 72 75 63 74 75 72 65 20 28 78 4d 75 s structure (xMu
36e20 74 65 78 41 6c 6c 6f 63 2c 0a 2a 2a 20 78 4d 75 texAlloc,.** xMu
36e30 74 65 78 46 72 65 65 2c 20 78 4d 75 74 65 78 45 texFree, xMutexE
36e40 6e 74 65 72 2c 20 78 4d 75 74 65 78 54 72 79 2c nter, xMutexTry,
36e50 20 78 4d 75 74 65 78 4c 65 61 76 65 2c 20 78 4d xMutexLeave, xM
36e60 75 74 65 78 48 65 6c 64 20 61 6e 64 0a 2a 2a 20 utexHeld and.**
36e70 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29 20 69 xMutexNotheld) i
36e80 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 66 6f 6c mplement the fol
36e90 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65 lowing interface
36ea0 73 20 28 72 65 73 70 65 63 74 69 76 65 6c 79 29 s (respectively)
36eb0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
36ec0 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 <li> [sqlite3
36ed0 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 _mutex_alloc()]
36ee0 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 </li>.** <li>
36ef0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
36f00 66 72 65 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a free()] </li>.**
36f10 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 <li> [sqlite
36f20 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 5d 3_mutex_enter()]
36f30 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e </li>.** <li>
36f40 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 [sqlite3_mutex
36f50 5f 74 72 79 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a _try()] </li>.**
36f60 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 <li> [sqlite
36f70 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 5d 3_mutex_leave()]
36f80 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e </li>.** <li>
36f90 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 [sqlite3_mutex
36fa0 5f 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a _held()] </li>.*
36fb0 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 * <li> [sqlit
36fc0 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 e3_mutex_notheld
36fd0 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 ()] </li>.** </u
36fe0 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 6e 6c l>.**.** The onl
36ff0 79 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 y difference is
37000 74 68 61 74 20 74 68 65 20 70 75 62 6c 69 63 20 that the public
37010 73 71 6c 69 74 65 33 5f 58 58 58 20 66 75 6e 63 sqlite3_XXX func
37020 74 69 6f 6e 73 20 65 6e 75 6d 65 72 61 74 65 64 tions enumerated
37030 0a 2a 2a 20 61 62 6f 76 65 20 73 69 6c 65 6e 74 .** above silent
37040 6c 79 20 69 67 6e 6f 72 65 20 61 6e 79 20 69 6e ly ignore any in
37050 76 6f 63 61 74 69 6f 6e 73 20 74 68 61 74 20 70 vocations that p
37060 61 73 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 ass a NULL point
37070 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 er instead.** of
37080 20 61 20 76 61 6c 69 64 20 6d 75 74 65 78 20 68 a valid mutex h
37090 61 6e 64 6c 65 2e 20 54 68 65 20 69 6d 70 6c 65 andle. The imple
370a0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 mentations of th
370b0 65 20 6d 65 74 68 6f 64 73 20 64 65 66 69 6e 65 e methods define
370c0 64 0a 2a 2a 20 62 79 20 74 68 69 73 20 73 74 72 d.** by this str
370d0 75 63 74 75 72 65 20 61 72 65 20 6e 6f 74 20 72 ucture are not r
370e0 65 71 75 69 72 65 64 20 74 6f 20 68 61 6e 64 6c equired to handl
370f0 65 20 74 68 69 73 20 63 61 73 65 2c 20 74 68 65 e this case, the
37100 20 72 65 73 75 6c 74 73 0a 2a 2a 20 6f 66 20 70 results.** of p
37110 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f assing a NULL po
37120 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 inter instead of
37130 20 61 20 76 61 6c 69 64 20 6d 75 74 65 78 20 68 a valid mutex h
37140 61 6e 64 6c 65 20 61 72 65 20 75 6e 64 65 66 69 andle are undefi
37150 6e 65 64 0a 2a 2a 20 28 69 2e 65 2e 20 69 74 20 ned.** (i.e. it
37160 69 73 20 61 63 63 65 70 74 61 62 6c 65 20 74 6f is acceptable to
37170 20 70 72 6f 76 69 64 65 20 61 6e 20 69 6d 70 6c provide an impl
37180 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 ementation that
37190 73 65 67 66 61 75 6c 74 73 20 69 66 0a 2a 2a 20 segfaults if.**
371a0 69 74 20 69 73 20 70 61 73 73 65 64 20 61 20 4e it is passed a N
371b0 55 4c 4c 20 70 6f 69 6e 74 65 72 29 2e 0a 2a 2a ULL pointer)..**
371c0 0a 2a 2a 20 54 68 65 20 78 4d 75 74 65 78 49 6e .** The xMutexIn
371d0 69 74 28 29 20 6d 65 74 68 6f 64 20 6d 75 73 74 it() method must
371e0 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 be threadsafe.
371f0 20 49 74 20 6d 75 73 74 20 62 65 20 68 61 72 6d It must be harm
37200 6c 65 73 73 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b less to.** invok
37210 65 20 78 4d 75 74 65 78 49 6e 69 74 28 29 20 6d e xMutexInit() m
37220 75 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 utiple times wit
37230 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f hin the same pro
37240 63 65 73 73 20 61 6e 64 20 77 69 74 68 6f 75 74 cess and without
37250 0a 2a 2a 20 69 6e 74 65 72 76 65 6e 69 6e 67 20 .** intervening
37260 63 61 6c 6c 73 20 74 6f 20 78 4d 75 74 65 78 45 calls to xMutexE
37270 6e 64 28 29 2e 20 20 53 65 63 6f 6e 64 20 61 6e nd(). Second an
37280 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c d subsequent cal
37290 6c 73 20 74 6f 0a 2a 2a 20 78 4d 75 74 65 78 49 ls to.** xMutexI
372a0 6e 69 74 28 29 20 6d 75 73 74 20 62 65 20 6e 6f nit() must be no
372b0 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 78 4d 75 74 -ops..**.** xMut
372c0 65 78 49 6e 69 74 28 29 20 6d 75 73 74 20 6e 6f exInit() must no
372d0 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d 65 6d t use SQLite mem
372e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 ory allocation (
372f0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
37300 29 5d 0a 2a 2a 20 61 6e 64 20 69 74 73 20 61 73 )].** and its as
37310 73 6f 63 69 61 74 65 73 29 2e 20 20 53 69 6d 69 sociates). Simi
37320 6c 61 72 6c 79 2c 20 78 4d 75 74 65 78 41 6c 6c larly, xMutexAll
37330 6f 63 28 29 20 6d 75 73 74 20 6e 6f 74 20 75 73 oc() must not us
37340 65 20 53 51 4c 69 74 65 20 6d 65 6d 6f 72 79 0a e SQLite memory.
37350 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f ** allocation fo
37360 72 20 61 20 73 74 61 74 69 63 20 6d 75 74 65 78 r a static mutex
37370 2e 20 20 48 6f 77 65 76 65 72 20 78 4d 75 74 65 . However xMute
37380 78 41 6c 6c 6f 63 28 29 20 6d 61 79 20 75 73 65 xAlloc() may use
37390 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 65 6d 6f 72 SQLite.** memor
373a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 y allocation for
373b0 20 61 20 66 61 73 74 20 6f 72 20 72 65 63 75 72 a fast or recur
373c0 73 69 76 65 20 6d 75 74 65 78 2e 0a 2a 2a 0a 2a sive mutex..**.*
373d0 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e * SQLite will in
373e0 76 6f 6b 65 20 74 68 65 20 78 4d 75 74 65 78 45 voke the xMutexE
373f0 6e 64 28 29 20 6d 65 74 68 6f 64 20 77 68 65 6e nd() method when
37400 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f [sqlite3_shutdo
37410 77 6e 28 29 5d 20 69 73 0a 2a 2a 20 63 61 6c 6c wn()] is.** call
37420 65 64 2c 20 62 75 74 20 6f 6e 6c 79 20 69 66 20 ed, but only if
37430 74 68 65 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 the prior call t
37440 6f 20 78 4d 75 74 65 78 49 6e 69 74 20 72 65 74 o xMutexInit ret
37450 75 72 6e 65 64 20 53 51 4c 49 54 45 5f 4f 4b 2e urned SQLITE_OK.
37460 0a 2a 2a 20 49 66 20 78 4d 75 74 65 78 49 6e 69 .** If xMutexIni
37470 74 20 66 61 69 6c 73 20 69 6e 20 61 6e 79 20 77 t fails in any w
37480 61 79 2c 20 69 74 20 69 73 20 65 78 70 65 63 74 ay, it is expect
37490 65 64 20 74 6f 20 63 6c 65 61 6e 20 75 70 20 61 ed to clean up a
374a0 66 74 65 72 20 69 74 73 65 6c 66 0a 2a 2a 20 70 fter itself.** p
374b0 72 69 6f 72 20 74 6f 20 72 65 74 75 72 6e 69 6e rior to returnin
374c0 67 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 g..*/.typedef st
374d0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 ruct sqlite3_mut
374e0 65 78 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 ex_methods sqlit
374f0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 e3_mutex_methods
37500 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 ;.struct sqlite3
37510 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 20 7b _mutex_methods {
37520 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 49 . int (*xMutexI
37530 6e 69 74 29 28 76 6f 69 64 29 3b 0a 20 20 69 6e nit)(void);. in
37540 74 20 28 2a 78 4d 75 74 65 78 45 6e 64 29 28 76 t (*xMutexEnd)(v
37550 6f 69 64 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f oid);. sqlite3_
37560 6d 75 74 65 78 20 2a 28 2a 78 4d 75 74 65 78 41 mutex *(*xMutexA
37570 6c 6c 6f 63 29 28 69 6e 74 29 3b 0a 20 20 76 6f lloc)(int);. vo
37580 69 64 20 28 2a 78 4d 75 74 65 78 46 72 65 65 29 id (*xMutexFree)
37590 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a (sqlite3_mutex *
375a0 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 74 );. void (*xMut
375b0 65 78 45 6e 74 65 72 29 28 73 71 6c 69 74 65 33 exEnter)(sqlite3
375c0 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 69 6e 74 _mutex *);. int
375d0 20 28 2a 78 4d 75 74 65 78 54 72 79 29 28 73 71 (*xMutexTry)(sq
375e0 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a lite3_mutex *);.
375f0 20 20 76 6f 69 64 20 28 2a 78 4d 75 74 65 78 4c void (*xMutexL
37600 65 61 76 65 29 28 73 71 6c 69 74 65 33 5f 6d 75 eave)(sqlite3_mu
37610 74 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a tex *);. int (*
37620 78 4d 75 74 65 78 48 65 6c 64 29 28 73 71 6c 69 xMutexHeld)(sqli
37630 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 te3_mutex *);.
37640 69 6e 74 20 28 2a 78 4d 75 74 65 78 4e 6f 74 68 int (*xMutexNoth
37650 65 6c 64 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 eld)(sqlite3_mut
37660 65 78 20 2a 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a ex *);.};../*.**
37670 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 CAPI3REF: Mutex
37680 20 56 65 72 69 66 69 63 61 74 69 6f 6e 20 52 6f Verification Ro
37690 75 74 69 6e 65 73 20 7b 48 31 37 30 38 30 7d 20 utines {H17080}
376a0 3c 53 32 30 31 33 30 3e 20 3c 53 33 30 38 30 30 <S20130> <S30800
376b0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 >.**.** The sqli
376c0 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 te3_mutex_held()
376d0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 and sqlite3_mut
376e0 65 78 5f 6e 6f 74 68 65 6c 64 28 29 20 72 6f 75 ex_notheld() rou
376f0 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 69 6e 74 tines.** are int
37700 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e ended for use in
37710 73 69 64 65 20 61 73 73 65 72 74 28 29 20 73 74 side assert() st
37720 61 74 65 6d 65 6e 74 73 2e 20 7b 48 31 37 30 38 atements. {H1708
37730 31 7d 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 1} The SQLite co
37740 72 65 0a 2a 2a 20 6e 65 76 65 72 20 75 73 65 73 re.** never uses
37750 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
37760 65 78 63 65 70 74 20 69 6e 73 69 64 65 20 61 6e except inside an
37770 20 61 73 73 65 72 74 28 29 20 61 6e 64 20 61 70 assert() and ap
37780 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 plications.** ar
37790 65 20 61 64 76 69 73 65 64 20 74 6f 20 66 6f 6c e advised to fol
377a0 6c 6f 77 20 74 68 65 20 6c 65 61 64 20 6f 66 20 low the lead of
377b0 74 68 65 20 63 6f 72 65 2e 20 20 7b 48 31 37 30 the core. {H170
377c0 38 32 7d 20 54 68 65 20 63 6f 72 65 20 6f 6e 6c 82} The core onl
377d0 79 0a 2a 2a 20 70 72 6f 76 69 64 65 73 20 69 6d y.** provides im
377e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f plementations fo
377f0 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 r these routines
37800 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 when it is comp
37810 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 iled.** with the
37820 20 53 51 4c 49 54 45 5f 44 45 42 55 47 20 66 6c SQLITE_DEBUG fl
37830 61 67 2e 20 20 7b 41 31 37 30 38 37 7d 20 45 78 ag. {A17087} Ex
37840 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 6d 70 ternal mutex imp
37850 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 lementations.**
37860 61 72 65 20 6f 6e 6c 79 20 72 65 71 75 69 72 65 are only require
37870 64 20 74 6f 20 70 72 6f 76 69 64 65 20 74 68 65 d to provide the
37880 73 65 20 72 6f 75 74 69 6e 65 73 20 69 66 20 53 se routines if S
37890 51 4c 49 54 45 5f 44 45 42 55 47 20 69 73 0a 2a QLITE_DEBUG is.*
378a0 2a 20 64 65 66 69 6e 65 64 20 61 6e 64 20 69 66 * defined and if
378b0 20 4e 44 45 42 55 47 20 69 73 20 6e 6f 74 20 64 NDEBUG is not d
378c0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 efined..**.** {H
378d0 31 37 30 38 33 7d 20 54 68 65 73 65 20 72 6f 75 17083} These rou
378e0 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 72 65 74 tines should ret
378f0 75 72 6e 20 74 72 75 65 20 69 66 20 74 68 65 20 urn true if the
37900 6d 75 74 65 78 20 69 6e 20 74 68 65 69 72 20 61 mutex in their a
37910 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 68 65 rgument.** is he
37920 6c 64 20 6f 72 20 6e 6f 74 20 68 65 6c 64 2c 20 ld or not held,
37930 72 65 73 70 65 63 74 69 76 65 6c 79 2c 20 62 79 respectively, by
37940 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 the calling thr
37950 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 7b 58 31 37 30 ead..**.** {X170
37960 38 34 7d 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 84} The implemen
37970 74 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 72 65 tation is not re
37980 71 75 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64 quired to provid
37990 65 64 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 ed versions of t
379a0 68 65 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 hese.** routines
379b0 20 74 68 61 74 20 61 63 74 75 61 6c 6c 79 20 77 that actually w
379c0 6f 72 6b 2e 20 49 66 20 74 68 65 20 69 6d 70 6c ork. If the impl
379d0 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 ementation does
379e0 6e 6f 74 20 70 72 6f 76 69 64 65 20 77 6f 72 6b not provide work
379f0 69 6e 67 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 ing.** versions
37a00 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 of these routine
37a10 73 2c 20 69 74 20 73 68 6f 75 6c 64 20 61 74 20 s, it should at
37a20 6c 65 61 73 74 20 70 72 6f 76 69 64 65 20 73 74 least provide st
37a30 75 62 73 20 74 68 61 74 20 61 6c 77 61 79 73 0a ubs that always.
37a40 2a 2a 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 ** return true s
37a50 6f 20 74 68 61 74 20 6f 6e 65 20 64 6f 65 73 20 o that one does
37a60 6e 6f 74 20 67 65 74 20 73 70 75 72 69 6f 75 73 not get spurious
37a70 20 61 73 73 65 72 74 69 6f 6e 20 66 61 69 6c 75 assertion failu
37a80 72 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 res..**.** {H170
37a90 38 35 7d 20 49 66 20 74 68 65 20 61 72 67 75 6d 85} If the argum
37aa0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d ent to sqlite3_m
37ab0 75 74 65 78 5f 68 65 6c 64 28 29 20 69 73 20 61 utex_held() is a
37ac0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 NULL pointer th
37ad0 65 6e 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e en.** the routin
37ae0 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 e should return
37af0 31 2e 20 20 7b 45 4e 44 7d 20 54 68 69 73 20 73 1. {END} This s
37b00 65 65 6d 73 20 63 6f 75 6e 74 65 72 2d 69 6e 74 eems counter-int
37b10 75 69 74 69 76 65 20 73 69 6e 63 65 0a 2a 2a 20 uitive since.**
37b20 63 6c 65 61 72 6c 79 20 74 68 65 20 6d 75 74 65 clearly the mute
37b30 78 20 63 61 6e 6e 6f 74 20 62 65 20 68 65 6c 64 x cannot be held
37b40 20 69 66 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 if it does not
37b50 65 78 69 73 74 2e 20 20 42 75 74 20 74 68 65 0a exist. But the.
37b60 2a 2a 20 74 68 65 20 72 65 61 73 6f 6e 20 74 68 ** the reason th
37b70 65 20 6d 75 74 65 78 20 64 6f 65 73 20 6e 6f 74 e mutex does not
37b80 20 65 78 69 73 74 20 69 73 20 62 65 63 61 75 73 exist is becaus
37b90 65 20 74 68 65 20 62 75 69 6c 64 20 69 73 20 6e e the build is n
37ba0 6f 74 0a 2a 2a 20 75 73 69 6e 67 20 6d 75 74 65 ot.** using mute
37bb0 78 65 73 2e 20 20 41 6e 64 20 77 65 20 64 6f 20 xes. And we do
37bc0 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 61 73 73 not want the ass
37bd0 65 72 74 28 29 20 63 6f 6e 74 61 69 6e 69 6e 67 ert() containing
37be0 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 the.** call to
37bf0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 sqlite3_mutex_he
37c00 6c 64 28 29 20 74 6f 20 66 61 69 6c 2c 20 73 6f ld() to fail, so
37c10 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 a non-zero retu
37c20 72 6e 20 69 73 0a 2a 2a 20 74 68 65 20 61 70 70 rn is.** the app
37c30 72 6f 70 72 69 61 74 65 20 74 68 69 6e 67 20 74 ropriate thing t
37c40 6f 20 64 6f 2e 20 20 7b 48 31 37 30 38 36 7d 20 o do. {H17086}
37c50 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 The sqlite3_mute
37c60 78 5f 6e 6f 74 68 65 6c 64 28 29 0a 2a 2a 20 69 x_notheld().** i
37c70 6e 74 65 72 66 61 63 65 20 73 68 6f 75 6c 64 20 nterface should
37c80 61 6c 73 6f 20 72 65 74 75 72 6e 20 31 20 77 68 also return 1 wh
37c90 65 6e 20 67 69 76 65 6e 20 61 20 4e 55 4c 4c 20 en given a NULL
37ca0 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49 pointer..*/.SQLI
37cb0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
37cc0 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 73 71 e3_mutex_held(sq
37cd0 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 53 lite3_mutex*);.S
37ce0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
37cf0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 lite3_mutex_noth
37d00 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 eld(sqlite3_mute
37d10 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 x*);../*.** CAPI
37d20 33 52 45 46 3a 20 4d 75 74 65 78 20 54 79 70 65 3REF: Mutex Type
37d30 73 20 7b 48 31 37 30 30 31 7d 20 3c 48 31 37 30 s {H17001} <H170
37d40 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 00>.**.** The [s
37d50 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c qlite3_mutex_all
37d60 6f 63 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 oc()] interface
37d70 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
37d80 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 69 63 68 rgument.** which
37d90 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 is one of these
37da0 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e integer constan
37db0 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 ts..**.** The se
37dc0 74 20 6f 66 20 73 74 61 74 69 63 20 6d 75 74 65 t of static mute
37dd0 78 65 73 20 6d 61 79 20 63 68 61 6e 67 65 20 66 xes may change f
37de0 72 6f 6d 20 6f 6e 65 20 53 51 4c 69 74 65 20 72 rom one SQLite r
37df0 65 6c 65 61 73 65 20 74 6f 20 74 68 65 0a 2a 2a elease to the.**
37e00 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 next. Applicat
37e10 69 6f 6e 73 20 74 68 61 74 20 6f 76 65 72 72 69 ions that overri
37e20 64 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 de the built-in
37e30 6d 75 74 65 78 20 6c 6f 67 69 63 20 6d 75 73 74 mutex logic must
37e40 20 62 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 be.** prepared
37e50 74 6f 20 61 63 63 6f 6d 6d 6f 64 61 74 65 20 61 to accommodate a
37e60 64 64 69 74 69 6f 6e 61 6c 20 73 74 61 74 69 63 dditional static
37e70 20 6d 75 74 65 78 65 73 2e 0a 2a 2f 0a 23 64 65 mutexes..*/.#de
37e80 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 fine SQLITE_MUTE
37e90 58 5f 46 41 53 54 20 20 20 20 20 20 20 20 20 20 X_FAST
37ea0 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0.#define SQL
37eb0 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 ITE_MUTEX_RECURS
37ec0 49 56 45 20 20 20 20 20 20 20 20 31 0a 23 64 65 IVE 1.#de
37ed0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 fine SQLITE_MUTE
37ee0 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 20 X_STATIC_MASTER
37ef0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 2.#define SQL
37f00 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 ITE_MUTEX_STATIC
37f10 5f 4d 45 4d 20 20 20 20 20 20 20 33 20 20 2f 2a _MEM 3 /*
37f20 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
37f30 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
37f40 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 ITE_MUTEX_STATIC
37f50 5f 4d 45 4d 32 20 20 20 20 20 20 34 20 20 2f 2a _MEM2 4 /*
37f60 20 4e 4f 54 20 55 53 45 44 20 2a 2f 0a 23 64 65 NOT USED */.#de
37f70 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 fine SQLITE_MUTE
37f80 58 5f 53 54 41 54 49 43 5f 4f 50 45 4e 20 20 20 X_STATIC_OPEN
37f90 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 4 /* sqlite3
37fa0 42 74 72 65 65 4f 70 65 6e 28 29 20 2a 2f 0a 23 BtreeOpen() */.#
37fb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 define SQLITE_MU
37fc0 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 20 TEX_STATIC_PRNG
37fd0 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 5 /* sqlit
37fe0 65 33 5f 72 61 6e 64 6f 6d 28 29 20 2a 2f 0a 23 e3_random() */.#
37ff0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 define SQLITE_MU
38000 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 20 20 TEX_STATIC_LRU
38010 20 20 20 20 20 36 20 20 2f 2a 20 6c 72 75 20 70 6 /* lru p
38020 61 67 65 20 6c 69 73 74 20 2a 2f 0a 23 64 65 66 age list */.#def
38030 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 ine SQLITE_MUTEX
38040 5f 53 54 41 54 49 43 5f 4c 52 55 32 20 20 20 20 _STATIC_LRU2
38050 20 20 37 20 20 2f 2a 20 6c 72 75 20 70 61 67 65 7 /* lru page
38060 20 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 list */../*.**
38070 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 CAPI3REF: Retrie
38080 76 65 20 74 68 65 20 6d 75 74 65 78 20 66 6f 72 ve the mutex for
38090 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a database conn
380a0 65 63 74 69 6f 6e 20 7b 48 31 37 30 30 32 7d 20 ection {H17002}
380b0 3c 48 31 37 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <H17000>.**.** T
380c0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 his interface re
380d0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
380e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 the [sqlite3_mut
380f0 65 78 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 ex] object that
38100 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 65 73 20 61 .** serializes a
38110 63 63 65 73 73 20 74 6f 20 74 68 65 20 5b 64 61 ccess to the [da
38120 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
38130 6e 5d 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 n] given in the
38140 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 65 6e argument.** when
38150 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 the [threading
38160 6d 6f 64 65 5d 20 69 73 20 53 65 72 69 61 6c 69 mode] is Seriali
38170 7a 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b zed..** If the [
38180 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
38190 69 73 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 is Single-thread
381a0 20 6f 72 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 or Multi-thread
381b0 20 74 68 65 6e 20 74 68 69 73 0a 2a 2a 20 72 6f then this.** ro
381c0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 utine returns a
381d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f NULL pointer..*/
381e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 .SQLITE_API sqli
381f0 74 65 33 5f 6d 75 74 65 78 20 2a 73 71 6c 69 74 te3_mutex *sqlit
38200 65 33 5f 64 62 5f 6d 75 74 65 78 28 73 71 6c 69 e3_db_mutex(sqli
38210 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 te3*);../*.** CA
38220 50 49 33 52 45 46 3a 20 4c 6f 77 2d 4c 65 76 65 PI3REF: Low-Leve
38230 6c 20 43 6f 6e 74 72 6f 6c 20 4f 66 20 44 61 74 l Control Of Dat
38240 61 62 61 73 65 20 46 69 6c 65 73 20 7b 48 31 31 abase Files {H11
38250 33 30 30 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 300} <S30800>.**
38260 0a 2a 2a 20 7b 48 31 31 33 30 31 7d 20 54 68 65 .** {H11301} The
38270 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 [sqlite3_file_c
38280 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 ontrol()] interf
38290 61 63 65 20 6d 61 6b 65 73 20 61 20 64 69 72 65 ace makes a dire
382a0 63 74 20 63 61 6c 6c 20 74 6f 20 74 68 65 0a 2a ct call to the.*
382b0 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d * xFileControl m
382c0 65 74 68 6f 64 20 66 6f 72 20 74 68 65 20 5b 73 ethod for the [s
382d0 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
382e0 73 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 s] object associ
382f0 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 61 20 70 ated.** with a p
38300 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 articular databa
38310 73 65 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 se identified by
38320 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
38330 6d 65 6e 74 2e 20 7b 48 31 31 33 30 32 7d 20 54 ment. {H11302} T
38340 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 he.** name of th
38350 65 20 64 61 74 61 62 61 73 65 20 69 73 20 74 68 e database is th
38360 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 e name assigned
38370 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 to the database
38380 62 79 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 by the.** <a hre
38390 66 3d 22 6c 61 6e 67 5f 61 74 74 61 63 68 2e 68 f="lang_attach.h
383a0 74 6d 6c 22 3e 41 54 54 41 43 48 3c 2f 61 3e 20 tml">ATTACH</a>
383b0 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 68 61 74 SQL command that
383c0 20 6f 70 65 6e 65 64 20 74 68 65 0a 2a 2a 20 64 opened the.** d
383d0 61 74 61 62 61 73 65 2e 20 7b 48 31 31 33 30 33 atabase. {H11303
383e0 7d 20 54 6f 20 63 6f 6e 74 72 6f 6c 20 74 68 65 } To control the
383f0 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 main database f
38400 69 6c 65 2c 20 75 73 65 20 74 68 65 20 6e 61 6d ile, use the nam
38410 65 20 22 6d 61 69 6e 22 0a 2a 2a 20 6f 72 20 61 e "main".** or a
38420 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 7b NULL pointer. {
38430 48 31 31 33 30 34 7d 20 54 68 65 20 74 68 69 72 H11304} The thir
38440 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 d and fourth par
38450 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 ameters to this
38460 72 6f 75 74 69 6e 65 0a 2a 2a 20 61 72 65 20 70 routine.** are p
38470 61 73 73 65 64 20 64 69 72 65 63 74 6c 79 20 74 assed directly t
38480 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 73 65 hrough to the se
38490 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 70 cond and third p
384a0 61 72 61 6d 65 74 65 72 73 20 6f 66 0a 2a 2a 20 arameters of.**
384b0 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c the xFileControl
384c0 20 6d 65 74 68 6f 64 2e 20 20 7b 48 31 31 33 30 method. {H1130
384d0 35 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 5} The return va
384e0 6c 75 65 20 6f 66 20 74 68 65 20 78 46 69 6c 65 lue of the xFile
384f0 43 6f 6e 74 72 6f 6c 0a 2a 2a 20 6d 65 74 68 6f Control.** metho
38500 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 72 65 d becomes the re
38510 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 turn value of th
38520 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a 2a is routine..**.*
38530 2a 20 7b 48 31 31 33 30 36 7d 20 49 66 20 74 68 * {H11306} If th
38540 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
38550 65 72 20 28 7a 44 62 4e 61 6d 65 29 20 64 6f 65 er (zDbName) doe
38560 73 20 6e 6f 74 20 6d 61 74 63 68 20 74 68 65 20 s not match the
38570 6e 61 6d 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f name of any.** o
38580 70 65 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c pen database fil
38590 65 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 45 e, then SQLITE_E
385a0 52 52 4f 52 20 69 73 20 72 65 74 75 72 6e 65 64 RROR is returned
385b0 2e 20 7b 48 31 31 33 30 37 7d 20 54 68 69 73 20 . {H11307} This
385c0 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 error.** code is
385d0 20 6e 6f 74 20 72 65 6d 65 6d 62 65 72 65 64 20 not remembered
385e0 61 6e 64 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 and will not be
385f0 72 65 63 61 6c 6c 65 64 20 62 79 20 5b 73 71 6c recalled by [sql
38600 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 0a ite3_errcode()].
38610 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 ** or [sqlite3_e
38620 72 72 6d 73 67 28 29 5d 2e 20 7b 41 31 31 33 30 rrmsg()]. {A1130
38630 38 7d 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 8} The underlyin
38640 67 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d g xFileControl m
38650 65 74 68 6f 64 20 6d 69 67 68 74 0a 2a 2a 20 61 ethod might.** a
38660 6c 73 6f 20 72 65 74 75 72 6e 20 53 51 4c 49 54 lso return SQLIT
38670 45 5f 45 52 52 4f 52 2e 20 20 7b 41 31 31 33 30 E_ERROR. {A1130
38680 39 7d 20 54 68 65 72 65 20 69 73 20 6e 6f 20 77 9} There is no w
38690 61 79 20 74 6f 20 64 69 73 74 69 6e 67 75 69 73 ay to distinguis
386a0 68 20 62 65 74 77 65 65 6e 0a 2a 2a 20 61 6e 20 h between.** an
386b0 69 6e 63 6f 72 72 65 63 74 20 7a 44 62 4e 61 6d incorrect zDbNam
386c0 65 20 61 6e 64 20 61 6e 20 53 51 4c 49 54 45 5f e and an SQLITE_
386d0 45 52 52 4f 52 20 72 65 74 75 72 6e 20 66 72 6f ERROR return fro
386e0 6d 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 m the underlying
386f0 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c .** xFileControl
38700 20 6d 65 74 68 6f 64 2e 20 7b 45 4e 44 7d 0a 2a method. {END}.*
38710 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
38720 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 SQLITE_FCNTL_LOC
38730 4b 53 54 41 54 45 5d 0a 2a 2f 0a 53 51 4c 49 54 KSTATE].*/.SQLIT
38740 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
38750 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 73 3_file_control(s
38760 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 qlite3*, const c
38770 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 69 6e har *zDbName, in
38780 74 20 6f 70 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f t op, void*);../
38790 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 *.** CAPI3REF: T
387a0 65 73 74 69 6e 67 20 49 6e 74 65 72 66 61 63 65 esting Interface
387b0 20 7b 48 31 31 34 30 30 7d 20 3c 53 33 30 38 30 {H11400} <S3080
387c0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 0>.**.** The sql
387d0 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f ite3_test_contro
387e0 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 l() interface is
387f0 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f 75 used to read ou
38800 74 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 73 74 t internal.** st
38810 61 74 65 20 6f 66 20 53 51 4c 69 74 65 20 61 6e ate of SQLite an
38820 64 20 74 6f 20 69 6e 6a 65 63 74 20 66 61 75 6c d to inject faul
38830 74 73 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 66 ts into SQLite f
38840 6f 72 20 74 65 73 74 69 6e 67 0a 2a 2a 20 70 75 or testing.** pu
38850 72 70 6f 73 65 73 2e 20 20 54 68 65 20 66 69 72 rposes. The fir
38860 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 st parameter is
38870 61 6e 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 an operation cod
38880 65 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 e that determine
38890 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 2c s.** the number,
388a0 20 6d 65 61 6e 69 6e 67 2c 20 61 6e 64 20 6f 70 meaning, and op
388b0 65 72 61 74 69 6f 6e 20 6f 66 20 61 6c 6c 20 73 eration of all s
388c0 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 ubsequent parame
388d0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 ters..**.** This
388e0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f interface is no
388f0 74 20 66 6f 72 20 75 73 65 20 62 79 20 61 70 70 t for use by app
38900 6c 69 63 61 74 69 6f 6e 73 2e 20 20 49 74 20 65 lications. It e
38910 78 69 73 74 73 20 73 6f 6c 65 6c 79 0a 2a 2a 20 xists solely.**
38920 66 6f 72 20 76 65 72 69 66 79 69 6e 67 20 74 68 for verifying th
38930 65 20 63 6f 72 72 65 63 74 20 6f 70 65 72 61 74 e correct operat
38940 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 ion of the SQLit
38950 65 20 6c 69 62 72 61 72 79 2e 20 20 44 65 70 65 e library. Depe
38960 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 68 6f 77 20 nding.** on how
38970 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 the SQLite libra
38980 72 79 20 69 73 20 63 6f 6d 70 69 6c 65 64 2c 20 ry is compiled,
38990 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6d this interface m
389a0 69 67 68 74 20 6e 6f 74 20 65 78 69 73 74 2e 0a ight not exist..
389b0 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c **.** The detail
389c0 73 20 6f 66 20 74 68 65 20 6f 70 65 72 61 74 69 s of the operati
389d0 6f 6e 20 63 6f 64 65 73 2c 20 74 68 65 69 72 20 on codes, their
389e0 6d 65 61 6e 69 6e 67 73 2c 20 74 68 65 20 70 61 meanings, the pa
389f0 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 68 65 79 rameters.** they
38a00 20 74 61 6b 65 2c 20 61 6e 64 20 77 68 61 74 20 take, and what
38a10 74 68 65 79 20 64 6f 20 61 72 65 20 61 6c 6c 20 they do are all
38a20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 subject to chang
38a30 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 e without notice
38a40 2e 0a 2a 2a 20 55 6e 6c 69 6b 65 20 6d 6f 73 74 ..** Unlike most
38a50 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 41 of the SQLite A
38a60 50 49 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f PI, this functio
38a70 6e 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 n is not guarant
38a80 65 65 64 20 74 6f 0a 2a 2a 20 6f 70 65 72 61 74 eed to.** operat
38a90 65 20 63 6f 6e 73 69 73 74 65 6e 74 6c 79 20 66 e consistently f
38aa0 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 rom one release
38ab0 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a to the next..*/.
38ac0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
38ad0 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 qlite3_test_cont
38ae0 72 6f 6c 28 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 rol(int op, ...)
38af0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
38b00 46 3a 20 54 65 73 74 69 6e 67 20 49 6e 74 65 72 F: Testing Inter
38b10 66 61 63 65 20 4f 70 65 72 61 74 69 6f 6e 20 43 face Operation C
38b20 6f 64 65 73 20 7b 48 31 31 34 31 30 7d 20 3c 48 odes {H11410} <H
38b30 31 31 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 11400>.**.** The
38b40 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 se constants are
38b50 20 74 68 65 20 76 61 6c 69 64 20 6f 70 65 72 61 the valid opera
38b60 74 69 6f 6e 20 63 6f 64 65 20 70 61 72 61 6d 65 tion code parame
38b70 74 65 72 73 20 75 73 65 64 0a 2a 2a 20 61 73 20 ters used.** as
38b80 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
38b90 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 nt to [sqlite3_t
38ba0 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d 2e 0a est_control()]..
38bb0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 70 61 72 61 **.** These para
38bc0 6d 65 74 65 72 73 20 61 6e 64 20 74 68 65 69 72 meters and their
38bd0 20 6d 65 61 6e 69 6e 67 73 20 61 72 65 20 73 75 meanings are su
38be0 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 0a bject to change.
38bf0 2a 2a 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 ** without notic
38c00 65 2e 20 20 54 68 65 73 65 20 76 61 6c 75 65 73 e. These values
38c10 20 61 72 65 20 66 6f 72 20 74 65 73 74 69 6e 67 are for testing
38c20 20 70 75 72 70 6f 73 65 73 20 6f 6e 6c 79 2e 0a purposes only..
38c30 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 ** Applications
38c40 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 61 should not use a
38c50 6e 79 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 ny of these para
38c60 6d 65 74 65 72 73 20 6f 72 20 74 68 65 0a 2a 2a meters or the.**
38c70 20 5b 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 [sqlite3_test_c
38c80 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 ontrol()] interf
38c90 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ace..*/.#define
38ca0 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f SQLITE_TESTCTRL_
38cb0 50 52 4e 47 5f 53 41 56 45 20 20 20 20 20 20 20 PRNG_SAVE
38cc0 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 5.#defi
38cd0 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 ne SQLITE_TESTCT
38ce0 52 4c 5f 50 52 4e 47 5f 52 45 53 54 4f 52 45 20 RL_PRNG_RESTORE
38cf0 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 6.#d
38d00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 efine SQLITE_TES
38d10 54 43 54 52 4c 5f 50 52 4e 47 5f 52 45 53 45 54 TCTRL_PRNG_RESET
38d20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 7
38d30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
38d40 54 45 53 54 43 54 52 4c 5f 42 49 54 56 45 43 5f TESTCTRL_BITVEC_
38d50 54 45 53 54 20 20 20 20 20 20 20 20 20 20 20 20 TEST
38d60 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8.#define SQLI
38d70 54 45 5f 54 45 53 54 43 54 52 4c 5f 46 41 55 4c TE_TESTCTRL_FAUL
38d80 54 5f 49 4e 53 54 41 4c 4c 20 20 20 20 20 20 20 T_INSTALL
38d90 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 9.#define S
38da0 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 42 QLITE_TESTCTRL_B
38db0 45 4e 49 47 4e 5f 4d 41 4c 4c 4f 43 5f 48 4f 4f ENIGN_MALLOC_HOO
38dc0 4b 53 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e KS 10.#defin
38dd0 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 e SQLITE_TESTCTR
38de0 4c 5f 50 45 4e 44 49 4e 47 5f 42 59 54 45 20 20 L_PENDING_BYTE
38df0 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 11.#de
38e00 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 fine SQLITE_TEST
38e10 43 54 52 4c 5f 41 53 53 45 52 54 20 20 20 20 20 CTRL_ASSERT
38e20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 12.
38e30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
38e40 45 53 54 43 54 52 4c 5f 41 4c 57 41 59 53 20 20 ESTCTRL_ALWAYS
38e50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
38e60 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 13.#define SQLIT
38e70 45 5f 54 45 53 54 43 54 52 4c 5f 52 45 53 45 52 E_TESTCTRL_RESER
38e80 56 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 VE
38e90 20 20 20 31 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 14../*.** CAP
38ea0 49 33 52 45 46 3a 20 53 51 4c 69 74 65 20 52 75 I3REF: SQLite Ru
38eb0 6e 74 69 6d 65 20 53 74 61 74 75 73 20 7b 48 31 ntime Status {H1
38ec0 37 32 30 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 7200} <S60200>.*
38ed0 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a * EXPERIMENTAL.*
38ee0 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 *.** This interf
38ef0 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 ace is used to r
38f00 65 74 72 69 65 76 65 20 72 75 6e 74 69 6d 65 20 etrieve runtime
38f10 73 74 61 74 75 73 20 69 6e 66 6f 72 6d 61 74 69 status informati
38f20 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 on.** about the
38f30 70 72 65 66 6f 72 6d 61 6e 63 65 20 6f 66 20 53 preformance of S
38f40 51 4c 69 74 65 2c 20 61 6e 64 20 6f 70 74 69 6f QLite, and optio
38f50 6e 61 6c 6c 79 20 74 6f 20 72 65 73 65 74 20 76 nally to reset v
38f60 61 72 69 6f 75 73 0a 2a 2a 20 68 69 67 68 77 61 arious.** highwa
38f70 74 65 72 20 6d 61 72 6b 73 2e 20 20 54 68 65 20 ter marks. The
38f80 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 first argument i
38f90 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 s an integer cod
38fa0 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 70 65 e for.** the spe
38fb0 63 69 66 69 63 20 70 61 72 61 6d 65 74 65 72 20 cific parameter
38fc0 74 6f 20 6d 65 61 73 75 72 65 2e 20 20 52 65 63 to measure. Rec
38fd0 6f 67 6e 69 7a 65 64 20 69 6e 74 65 67 65 72 20 ognized integer
38fe0 63 6f 64 65 73 0a 2a 2a 20 61 72 65 20 6f 66 20 codes.** are of
38ff0 74 68 65 20 66 6f 72 6d 20 5b 53 51 4c 49 54 45 the form [SQLITE
39000 5f 53 54 41 54 55 53 5f 4d 45 4d 4f 52 59 5f 55 _STATUS_MEMORY_U
39010 53 45 44 20 7c 20 53 51 4c 49 54 45 5f 53 54 41 SED | SQLITE_STA
39020 54 55 53 5f 2e 2e 2e 5d 2e 0a 2a 2a 20 54 68 65 TUS_...]..** The
39030 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f current value o
39040 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 f the parameter
39050 69 73 20 72 65 74 75 72 6e 65 64 20 69 6e 74 6f is returned into
39060 20 2a 70 43 75 72 72 65 6e 74 2e 0a 2a 2a 20 54 *pCurrent..** T
39070 68 65 20 68 69 67 68 65 73 74 20 72 65 63 6f 72 he highest recor
39080 64 65 64 20 76 61 6c 75 65 20 69 73 20 72 65 74 ded value is ret
39090 75 72 6e 65 64 20 69 6e 20 2a 70 48 69 67 68 77 urned in *pHighw
390a0 61 74 65 72 2e 20 20 49 66 20 74 68 65 0a 2a 2a ater. If the.**
390b0 20 72 65 73 65 74 46 6c 61 67 20 69 73 20 74 72 resetFlag is tr
390c0 75 65 2c 20 74 68 65 6e 20 74 68 65 20 68 69 67 ue, then the hig
390d0 68 65 73 74 20 72 65 63 6f 72 64 20 76 61 6c 75 hest record valu
390e0 65 20 69 73 20 72 65 73 65 74 20 61 66 74 65 72 e is reset after
390f0 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74 65 72 20 .** *pHighwater
39100 69 73 20 77 72 69 74 74 65 6e 2e 20 53 6f 6d 65 is written. Some
39110 20 70 61 72 61 6d 65 74 65 72 73 20 64 6f 20 6e parameters do n
39120 6f 74 20 72 65 63 6f 72 64 20 74 68 65 20 68 69 ot record the hi
39130 67 68 65 73 74 0a 2a 2a 20 76 61 6c 75 65 2e 20 ghest.** value.
39140 20 46 6f 72 20 74 68 6f 73 65 20 70 61 72 61 6d For those param
39150 65 74 65 72 73 0a 2a 2a 20 6e 6f 74 68 69 6e 67 eters.** nothing
39160 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f is written into
39170 20 2a 70 48 69 67 68 77 61 74 65 72 20 61 6e 64 *pHighwater and
39180 20 74 68 65 20 72 65 73 65 74 46 6c 61 67 20 69 the resetFlag i
39190 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 20 4f 74 s ignored..** Ot
391a0 68 65 72 20 70 61 72 61 6d 65 74 65 72 73 20 72 her parameters r
391b0 65 63 6f 72 64 20 6f 6e 6c 79 20 74 68 65 20 68 ecord only the h
391c0 69 67 68 77 61 74 65 72 20 6d 61 72 6b 20 61 6e ighwater mark an
391d0 64 20 6e 6f 74 20 74 68 65 20 63 75 72 72 65 6e d not the curren
391e0 74 0a 2a 2a 20 76 61 6c 75 65 2e 20 20 46 6f 72 t.** value. For
391f0 20 74 68 65 73 65 20 6c 61 74 74 65 72 20 70 61 these latter pa
39200 72 61 6d 65 74 65 72 73 20 6e 6f 74 68 69 6e 67 rameters nothing
39210 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f is written into
39220 20 2a 70 43 75 72 72 65 6e 74 2e 0a 2a 2a 0a 2a *pCurrent..**.*
39230 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 * This routine r
39240 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b eturns SQLITE_OK
39250 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 on success and
39260 61 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 5b 65 a non-zero.** [e
39270 72 72 6f 72 20 63 6f 64 65 5d 20 6f 6e 20 66 61 rror code] on fa
39280 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 ilure..**.** Thi
39290 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 72 s routine is thr
392a0 65 61 64 73 61 66 65 20 62 75 74 20 69 73 20 6e eadsafe but is n
392b0 6f 74 20 61 74 6f 6d 69 63 2e 20 20 54 68 69 73 ot atomic. This
392c0 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 0a routine can be.
392d0 2a 2a 20 63 61 6c 6c 65 64 20 77 68 69 6c 65 20 ** called while
392e0 6f 74 68 65 72 20 74 68 72 65 61 64 73 20 61 72 other threads ar
392f0 65 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 73 61 e running the sa
39300 6d 65 20 6f 72 20 64 69 66 66 65 72 65 6e 74 20 me or different
39310 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 66 SQLite.** interf
39320 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 20 74 aces. However t
39330 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e he values return
39340 65 64 20 69 6e 20 2a 70 43 75 72 72 65 6e 74 20 ed in *pCurrent
39350 61 6e 64 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74 and.** *pHighwat
39360 65 72 20 72 65 66 6c 65 63 74 20 74 68 65 20 73 er reflect the s
39370 74 61 74 75 73 20 6f 66 20 53 51 4c 69 74 65 20 tatus of SQLite
39380 61 74 20 64 69 66 66 65 72 65 6e 74 20 70 6f 69 at different poi
39390 6e 74 73 20 69 6e 20 74 69 6d 65 0a 2a 2a 20 61 nts in time.** a
393a0 6e 64 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c nd it is possibl
393b0 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 e that another t
393c0 68 72 65 61 64 20 6d 69 67 68 74 20 63 68 61 6e hread might chan
393d0 67 65 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 ge the parameter
393e0 0a 2a 2a 20 69 6e 20 62 65 74 77 65 65 6e 20 74 .** in between t
393f0 68 65 20 74 69 6d 65 73 20 77 68 65 6e 20 2a 70 he times when *p
39400 43 75 72 72 65 6e 74 20 61 6e 64 20 2a 70 48 69 Current and *pHi
39410 67 68 77 61 74 65 72 20 61 72 65 20 77 72 69 74 ghwater are writ
39420 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ten..**.** See a
39430 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 62 lso: [sqlite3_db
39440 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2f 0a 53 51 _status()].*/.SQ
39450 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
39460 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 EXPERIMENTAL int
39470 20 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 sqlite3_status(
39480 69 6e 74 20 6f 70 2c 20 69 6e 74 20 2a 70 43 75 int op, int *pCu
39490 72 72 65 6e 74 2c 20 69 6e 74 20 2a 70 48 69 67 rrent, int *pHig
394a0 68 77 61 74 65 72 2c 20 69 6e 74 20 72 65 73 65 hwater, int rese
394b0 74 46 6c 61 67 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 tFlag);.../*.**
394c0 43 41 50 49 33 52 45 46 3a 20 53 74 61 74 75 73 CAPI3REF: Status
394d0 20 50 61 72 61 6d 65 74 65 72 73 20 7b 48 31 37 Parameters {H17
394e0 32 35 30 7d 20 3c 48 31 37 32 30 30 3e 0a 2a 2a 250} <H17200>.**
394f0 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a EXPERIMENTAL.**
39500 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 .** These intege
39510 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 73 69 r constants desi
39520 67 6e 61 74 65 20 76 61 72 69 6f 75 73 20 72 75 gnate various ru
39530 6e 2d 74 69 6d 65 20 73 74 61 74 75 73 20 70 61 n-time status pa
39540 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 68 61 74 rameters.** that
39550 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 can be returned
39560 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 by [sqlite3_sta
39570 74 75 73 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 tus()]..**.** <d
39580 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 l>.** <dt>SQLITE
39590 5f 53 54 41 54 55 53 5f 4d 45 4d 4f 52 59 5f 55 _STATUS_MEMORY_U
395a0 53 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e SED</dt>.** <dd>
395b0 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 This parameter i
395c0 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 61 6d s the current am
395d0 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 20 63 ount of memory c
395e0 68 65 63 6b 65 64 20 6f 75 74 0a 2a 2a 20 75 73 hecked out.** us
395f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c ing [sqlite3_mal
39600 6c 6f 63 28 29 5d 2c 20 65 69 74 68 65 72 20 64 loc()], either d
39610 69 72 65 63 74 6c 79 20 6f 72 20 69 6e 64 69 72 irectly or indir
39620 65 63 74 6c 79 2e 20 20 54 68 65 0a 2a 2a 20 66 ectly. The.** f
39630 69 67 75 72 65 20 69 6e 63 6c 75 64 65 73 20 63 igure includes c
39640 61 6c 6c 73 20 6d 61 64 65 20 74 6f 20 5b 73 71 alls made to [sq
39650 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
39660 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 by the applicati
39670 6f 6e 0a 2a 2a 20 61 6e 64 20 69 6e 74 65 72 6e on.** and intern
39680 61 6c 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 20 al memory usage
39690 62 79 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 by the SQLite li
396a0 62 72 61 72 79 2e 20 20 53 63 72 61 74 63 68 20 brary. Scratch
396b0 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 74 72 6f memory.** contro
396c0 6c 6c 65 64 20 62 79 20 5b 53 51 4c 49 54 45 5f lled by [SQLITE_
396d0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 CONFIG_SCRATCH]
396e0 61 6e 64 20 61 75 78 69 6c 69 61 72 79 20 70 61 and auxiliary pa
396f0 67 65 2d 63 61 63 68 65 0a 2a 2a 20 6d 65 6d 6f ge-cache.** memo
39700 72 79 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 ry controlled by
39710 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
39720 50 41 47 45 43 41 43 48 45 5d 20 69 73 20 6e 6f PAGECACHE] is no
39730 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 0a 2a 2a t included in.**
39740 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 2e this parameter.
39750 20 20 54 68 65 20 61 6d 6f 75 6e 74 20 72 65 74 The amount ret
39760 75 72 6e 65 64 20 69 73 20 74 68 65 20 73 75 6d urned is the sum
39770 20 6f 66 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 of the allocati
39780 6f 6e 0a 2a 2a 20 73 69 7a 65 73 20 61 73 20 72 on.** sizes as r
39790 65 70 6f 72 74 65 64 20 62 79 20 74 68 65 20 78 eported by the x
397a0 53 69 7a 65 20 6d 65 74 68 6f 64 20 69 6e 20 5b Size method in [
397b0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
397c0 6f 64 73 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ods].</dd>.**.**
397d0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 <dt>SQLITE_STAT
397e0 55 53 5f 4d 41 4c 4c 4f 43 5f 53 49 5a 45 3c 2f US_MALLOC_SIZE</
397f0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 dt>.** <dd>This
39800 70 61 72 61 6d 65 74 65 72 20 72 65 63 6f 72 64 parameter record
39810 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 6d 65 s the largest me
39820 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
39830 72 65 71 75 65 73 74 0a 2a 2a 20 68 61 6e 64 65 request.** hande
39840 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 d to [sqlite3_ma
39850 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 lloc()] or [sqli
39860 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 28 te3_realloc()] (
39870 6f 72 20 74 68 65 69 72 0a 2a 2a 20 69 6e 74 65 or their.** inte
39880 72 6e 61 6c 20 65 71 75 69 76 61 6c 65 6e 74 73 rnal equivalents
39890 29 2e 20 20 4f 6e 6c 79 20 74 68 65 20 76 61 6c ). Only the val
398a0 75 65 20 72 65 74 75 72 6e 65 64 20 69 6e 20 74 ue returned in t
398b0 68 65 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74 65 he.** *pHighwate
398c0 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b r parameter to [
398d0 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 sqlite3_status()
398e0 5d 20 69 73 20 6f 66 20 69 6e 74 65 72 65 73 74 ] is of interest
398f0 2e 20 20 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 . .** The value
39900 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 written into th
39910 65 20 2a 70 43 75 72 72 65 6e 74 20 70 61 72 61 e *pCurrent para
39920 6d 65 74 65 72 20 69 73 20 75 6e 64 65 66 69 6e meter is undefin
39930 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c ed.</dd>.**.** <
39940 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 dt>SQLITE_STATUS
39950 5f 50 41 47 45 43 41 43 48 45 5f 55 53 45 44 3c _PAGECACHE_USED<
39960 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 /dt>.** <dd>This
39970 20 70 61 72 61 6d 65 74 65 72 20 72 65 74 75 72 parameter retur
39980 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
39990 20 70 61 67 65 73 20 75 73 65 64 20 6f 75 74 20 pages used out
399a0 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 61 67 65 63 of the.** [pagec
399b0 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ache memory allo
399c0 63 61 74 6f 72 5d 20 74 68 61 74 20 77 61 73 20 cator] that was
399d0 63 6f 6e 66 69 67 75 72 65 64 20 75 73 69 6e 67 configured using
399e0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [SQLITE_CON
399f0 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 20 FIG_PAGECACHE].
39a00 20 54 68 65 0a 2a 2a 20 76 61 6c 75 65 20 72 65 The.** value re
39a10 74 75 72 6e 65 64 20 69 73 20 69 6e 20 70 61 67 turned is in pag
39a20 65 73 2c 20 6e 6f 74 20 69 6e 20 62 79 74 65 73 es, not in bytes
39a30 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
39a40 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 >SQLITE_STATUS_P
39a50 41 47 45 43 41 43 48 45 5f 4f 56 45 52 46 4c 4f AGECACHE_OVERFLO
39a60 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 W</dt>.** <dd>Th
39a70 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 74 is parameter ret
39a80 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
39a90 6f 66 20 62 79 74 65 73 20 6f 66 20 70 61 67 65 of bytes of page
39aa0 20 63 61 63 68 65 0a 2a 2a 20 61 6c 6c 6f 63 61 cache.** alloca
39ab0 74 69 6f 6e 20 77 68 69 63 68 20 63 6f 75 6c 64 tion which could
39ac0 20 6e 6f 74 20 62 65 20 73 74 61 74 69 73 66 69 not be statisfi
39ad0 65 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 ed by the [SQLIT
39ae0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 E_CONFIG_PAGECAC
39af0 48 45 5d 0a 2a 2a 20 62 75 66 66 65 72 20 61 6e HE].** buffer an
39b00 64 20 77 68 65 72 65 20 66 6f 72 63 65 64 20 74 d where forced t
39b10 6f 20 6f 76 65 72 66 6c 6f 77 20 74 6f 20 5b 73 o overflow to [s
39b20 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
39b30 2e 20 20 54 68 65 0a 2a 2a 20 72 65 74 75 72 6e . The.** return
39b40 65 64 20 76 61 6c 75 65 20 69 6e 63 6c 75 64 65 ed value include
39b50 73 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 74 68 s allocations th
39b60 61 74 20 6f 76 65 72 66 6c 6f 77 65 64 20 62 65 at overflowed be
39b70 63 61 75 73 65 20 74 68 65 79 0a 2a 2a 20 77 68 cause they.** wh
39b80 65 72 65 20 74 6f 6f 20 6c 61 72 67 65 20 28 74 ere too large (t
39b90 68 65 79 20 77 65 72 65 20 6c 61 72 67 65 72 20 hey were larger
39ba0 74 68 61 6e 20 74 68 65 20 22 73 7a 22 20 70 61 than the "sz" pa
39bb0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 rameter to.** [S
39bc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 QLITE_CONFIG_PAG
39bd0 45 43 41 43 48 45 5d 29 20 61 6e 64 20 61 6c 6c ECACHE]) and all
39be0 6f 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6f 76 ocations that ov
39bf0 65 72 66 6c 6f 77 65 64 20 62 65 63 61 75 73 65 erflowed because
39c00 0a 2a 2a 20 6e 6f 20 73 70 61 63 65 20 77 61 73 .** no space was
39c10 20 6c 65 66 74 20 69 6e 20 74 68 65 20 70 61 67 left in the pag
39c20 65 20 63 61 63 68 65 2e 3c 2f 64 64 3e 0a 2a 2a e cache.</dd>.**
39c30 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 .** <dt>SQLITE_S
39c40 54 41 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f TATUS_PAGECACHE_
39c50 53 49 5a 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 SIZE</dt>.** <dd
39c60 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 >This parameter
39c70 72 65 63 6f 72 64 73 20 74 68 65 20 6c 61 72 67 records the larg
39c80 65 73 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 est memory alloc
39c90 61 74 69 6f 6e 20 72 65 71 75 65 73 74 0a 2a 2a ation request.**
39ca0 20 68 61 6e 64 65 64 20 74 6f 20 5b 70 61 67 65 handed to [page
39cb0 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c cache memory all
39cc0 6f 63 61 74 6f 72 5d 2e 20 20 4f 6e 6c 79 20 74 ocator]. Only t
39cd0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
39ce0 64 20 69 6e 20 74 68 65 0a 2a 2a 20 2a 70 48 69 d in the.** *pHi
39cf0 67 68 77 61 74 65 72 20 70 61 72 61 6d 65 74 65 ghwater paramete
39d00 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 r to [sqlite3_st
39d10 61 74 75 73 28 29 5d 20 69 73 20 6f 66 20 69 6e atus()] is of in
39d20 74 65 72 65 73 74 2e 20 20 0a 2a 2a 20 54 68 65 terest. .** The
39d30 20 76 61 6c 75 65 20 77 72 69 74 74 65 6e 20 69 value written i
39d40 6e 74 6f 20 74 68 65 20 2a 70 43 75 72 72 65 6e nto the *pCurren
39d50 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 t parameter is u
39d60 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a ndefined.</dd>.*
39d70 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
39d80 53 54 41 54 55 53 5f 53 43 52 41 54 43 48 5f 55 STATUS_SCRATCH_U
39d90 53 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e SED</dt>.** <dd>
39da0 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 This parameter r
39db0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
39dc0 72 20 6f 66 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 r of allocations
39dd0 20 75 73 65 64 20 6f 75 74 20 6f 66 20 74 68 65 used out of the
39de0 0a 2a 2a 20 5b 73 63 72 61 74 63 68 20 6d 65 6d .** [scratch mem
39df0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 ory allocator] c
39e00 6f 6e 66 69 67 75 72 65 64 20 75 73 69 6e 67 0a onfigured using.
39e10 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ** [SQLITE_CONFI
39e20 47 5f 53 43 52 41 54 43 48 5d 2e 20 20 54 68 65 G_SCRATCH]. The
39e30 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
39e40 69 73 20 69 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e is in allocation
39e50 73 2c 20 6e 6f 74 0a 2a 2a 20 69 6e 20 62 79 74 s, not.** in byt
39e60 65 73 2e 20 20 53 69 6e 63 65 20 61 20 73 69 6e es. Since a sin
39e70 67 6c 65 20 74 68 72 65 61 64 20 6d 61 79 20 6f gle thread may o
39e80 6e 6c 79 20 68 61 76 65 20 6f 6e 65 20 73 63 72 nly have one scr
39e90 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a atch allocation.
39ea0 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 61 ** outstanding a
39eb0 74 20 74 69 6d 65 2c 20 74 68 69 73 20 70 61 72 t time, this par
39ec0 61 6d 65 74 65 72 20 61 6c 73 6f 20 72 65 70 6f ameter also repo
39ed0 72 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rts the number o
39ee0 66 20 74 68 72 65 61 64 73 0a 2a 2a 20 75 73 69 f threads.** usi
39ef0 6e 67 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 ng scratch memor
39f00 79 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 y at the same ti
39f10 6d 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c me.</dd>.**.** <
39f20 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 55 53 dt>SQLITE_STATUS
39f30 5f 53 43 52 41 54 43 48 5f 4f 56 45 52 46 4c 4f _SCRATCH_OVERFLO
39f40 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 W</dt>.** <dd>Th
39f50 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 74 is parameter ret
39f60 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
39f70 6f 66 20 62 79 74 65 73 20 6f 66 20 73 63 72 61 of bytes of scra
39f80 74 63 68 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c tch memory.** al
39f90 6c 6f 63 61 74 69 6f 6e 20 77 68 69 63 68 20 63 location which c
39fa0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 73 74 61 74 ould not be stat
39fb0 69 73 66 69 65 64 20 62 79 20 74 68 65 20 5b 53 isfied by the [S
39fc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 QLITE_CONFIG_SCR
39fd0 41 54 43 48 5d 0a 2a 2a 20 62 75 66 66 65 72 20 ATCH].** buffer
39fe0 61 6e 64 20 77 68 65 72 65 20 66 6f 72 63 65 64 and where forced
39ff0 20 74 6f 20 6f 76 65 72 66 6c 6f 77 20 74 6f 20 to overflow to
3a000 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
3a010 29 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 73 0a )]. The values.
3a020 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 63 6c ** returned incl
3a030 75 64 65 20 6f 76 65 72 66 6c 6f 77 73 20 62 65 ude overflows be
3a040 63 61 75 73 65 20 74 68 65 20 72 65 71 75 65 73 cause the reques
3a050 74 65 64 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 77 ted allocation w
3a060 61 73 20 74 6f 6f 0a 2a 2a 20 6c 61 72 67 65 72 as too.** larger
3a070 20 28 74 68 61 74 20 69 73 2c 20 62 65 63 61 75 (that is, becau
3a080 73 65 20 74 68 65 20 72 65 71 75 65 73 74 65 64 se the requested
3a090 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 77 61 73 20 allocation was
3a0a0 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 0a larger than the.
3a0b0 2a 2a 20 22 73 7a 22 20 70 61 72 61 6d 65 74 65 ** "sz" paramete
3a0c0 72 20 74 6f 20 5b 53 51 4c 49 54 45 5f 43 4f 4e r to [SQLITE_CON
3a0d0 46 49 47 5f 53 43 52 41 54 43 48 5d 29 20 61 6e FIG_SCRATCH]) an
3a0e0 64 20 62 65 63 61 75 73 65 20 6e 6f 20 73 63 72 d because no scr
3a0f0 61 74 63 68 20 62 75 66 66 65 72 0a 2a 2a 20 73 atch buffer.** s
3a100 6c 6f 74 73 20 77 65 72 65 20 61 76 61 69 6c 61 lots were availa
3a110 62 6c 65 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a ble..** </dd>.**
3a120 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 .** <dt>SQLITE_S
3a130 54 41 54 55 53 5f 53 43 52 41 54 43 48 5f 53 49 TATUS_SCRATCH_SI
3a140 5a 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 ZE</dt>.** <dd>T
3a150 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 65 his parameter re
3a160 63 6f 72 64 73 20 74 68 65 20 6c 61 72 67 65 73 cords the larges
3a170 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 t memory allocat
3a180 69 6f 6e 20 72 65 71 75 65 73 74 0a 2a 2a 20 68 ion request.** h
3a190 61 6e 64 65 64 20 74 6f 20 5b 73 63 72 61 74 63 anded to [scratc
3a1a0 68 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 h memory allocat
3a1b0 6f 72 5d 2e 20 20 4f 6e 6c 79 20 74 68 65 20 76 or]. Only the v
3a1c0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 6e alue returned in
3a1d0 20 74 68 65 0a 2a 2a 20 2a 70 48 69 67 68 77 61 the.** *pHighwa
3a1e0 74 65 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f ter parameter to
3a1f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 [sqlite3_status
3a200 28 29 5d 20 69 73 20 6f 66 20 69 6e 74 65 72 65 ()] is of intere
3a210 73 74 2e 20 20 0a 2a 2a 20 54 68 65 20 76 61 6c st. .** The val
3a220 75 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 ue written into
3a230 74 68 65 20 2a 70 43 75 72 72 65 6e 74 20 70 61 the *pCurrent pa
3a240 72 61 6d 65 74 65 72 20 69 73 20 75 6e 64 65 66 rameter is undef
3a250 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ined.</dd>.**.**
3a260 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 54 <dt>SQLITE_STAT
3a270 55 53 5f 50 41 52 53 45 52 5f 53 54 41 43 4b 3c US_PARSER_STACK<
3a280 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 /dt>.** <dd>This
3a290 20 70 61 72 61 6d 65 74 65 72 20 72 65 63 6f 72 parameter recor
3a2a0 64 73 20 74 68 65 20 64 65 65 70 65 73 74 20 70 ds the deepest p
3a2b0 61 72 73 65 72 20 73 74 61 63 6b 2e 20 20 49 74 arser stack. It
3a2c0 20 69 73 20 6f 6e 6c 79 0a 2a 2a 20 6d 65 61 6e is only.** mean
3a2d0 69 6e 67 66 75 6c 20 69 66 20 53 51 4c 69 74 65 ingful if SQLite
3a2e0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
3a2f0 68 20 5b 59 59 54 52 41 43 4b 4d 41 58 53 54 41 h [YYTRACKMAXSTA
3a300 43 4b 44 45 50 54 48 5d 2e 3c 2f 64 64 3e 0a 2a CKDEPTH].</dd>.*
3a310 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 4e 65 * </dl>.**.** Ne
3a320 77 20 73 74 61 74 75 73 20 70 61 72 61 6d 65 74 w status paramet
3a330 65 72 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 ers may be added
3a340 20 66 72 6f 6d 20 74 69 6d 65 20 74 6f 20 74 69 from time to ti
3a350 6d 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 me..*/.#define S
3a360 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 45 4d QLITE_STATUS_MEM
3a370 4f 52 59 5f 55 53 45 44 20 20 20 20 20 20 20 20 ORY_USED
3a380 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 0.#define SQLI
3a390 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45 43 41 TE_STATUS_PAGECA
3a3a0 43 48 45 5f 55 53 45 44 20 20 20 20 20 20 20 31 CHE_USED 1
3a3b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3a3c0 53 54 41 54 55 53 5f 50 41 47 45 43 41 43 48 45 STATUS_PAGECACHE
3a3d0 5f 4f 56 45 52 46 4c 4f 57 20 20 20 32 0a 23 64 _OVERFLOW 2.#d
3a3e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 efine SQLITE_STA
3a3f0 54 55 53 5f 53 43 52 41 54 43 48 5f 55 53 45 44 TUS_SCRATCH_USED
3a400 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 3.#defi
3a410 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 ne SQLITE_STATUS
3a420 5f 53 43 52 41 54 43 48 5f 4f 56 45 52 46 4c 4f _SCRATCH_OVERFLO
3a430 57 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 W 4.#define
3a440 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 41 SQLITE_STATUS_MA
3a450 4c 4c 4f 43 5f 53 49 5a 45 20 20 20 20 20 20 20 LLOC_SIZE
3a460 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 5.#define SQL
3a470 49 54 45 5f 53 54 41 54 55 53 5f 50 41 52 53 45 ITE_STATUS_PARSE
3a480 52 5f 53 54 41 43 4b 20 20 20 20 20 20 20 20 20 R_STACK
3a490 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 6.#define SQLITE
3a4a0 5f 53 54 41 54 55 53 5f 50 41 47 45 43 41 43 48 _STATUS_PAGECACH
3a4b0 45 5f 53 49 5a 45 20 20 20 20 20 20 20 37 0a 23 E_SIZE 7.#
3a4c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 define SQLITE_ST
3a4d0 41 54 55 53 5f 53 43 52 41 54 43 48 5f 53 49 5a ATUS_SCRATCH_SIZ
3a4e0 45 20 20 20 20 20 20 20 20 20 38 0a 0a 2f 2a 0a E 8../*.
3a4f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 ** CAPI3REF: Dat
3a500 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e abase Connection
3a510 20 53 74 61 74 75 73 20 7b 48 31 37 35 30 30 7d Status {H17500}
3a520 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 45 58 50 <S60200>.** EXP
3a530 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 ERIMENTAL.**.**
3a540 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 This interface i
3a550 73 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 s used to retrie
3a560 76 65 20 72 75 6e 74 69 6d 65 20 73 74 61 74 75 ve runtime statu
3a570 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 0a 2a s information .*
3a580 2a 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 * about a single
3a590 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
3a5a0 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72 ction]. The fir
3a5b0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 st argument is t
3a5c0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 he.** database c
3a5d0 6f 6e 6e 65 63 74 69 6f 6e 20 6f 62 6a 65 63 74 onnection object
3a5e0 20 74 6f 20 62 65 20 69 6e 74 65 72 72 6f 67 61 to be interroga
3a5f0 74 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 ted. The second
3a600 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 argument.** is
3a610 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f the parameter to
3a620 20 69 6e 74 65 72 72 6f 67 61 74 65 2e 20 20 43 interrogate. C
3a630 75 72 72 65 6e 74 6c 79 2c 20 74 68 65 20 6f 6e urrently, the on
3a640 6c 79 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 ly allowed value
3a650 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 65 63 6f .** for the seco
3a660 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
3a670 5b 53 51 4c 49 54 45 5f 44 42 53 54 41 54 55 53 [SQLITE_DBSTATUS
3a680 5f 4c 4f 4f 4b 41 53 49 44 45 5f 55 53 45 44 5d _LOOKASIDE_USED]
3a690 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 ..** Additional
3a6a0 6f 70 74 69 6f 6e 73 20 77 69 6c 6c 20 6c 69 6b options will lik
3a6b0 65 6c 79 20 61 70 70 65 61 72 20 69 6e 20 66 75 ely appear in fu
3a6c0 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 ture releases of
3a6d0 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 SQLite..**.** T
3a6e0 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 he current value
3a6f0 20 6f 66 20 74 68 65 20 72 65 71 75 65 73 74 65 of the requeste
3a700 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 77 d parameter is w
3a710 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 43 75 ritten into *pCu
3a720 72 0a 2a 2a 20 61 6e 64 20 74 68 65 20 68 69 67 r.** and the hig
3a730 68 65 73 74 20 69 6e 73 74 61 6e 74 61 6e 65 6f hest instantaneo
3a740 75 73 20 76 61 6c 75 65 20 69 73 20 77 72 69 74 us value is writ
3a750 74 65 6e 20 69 6e 74 6f 20 2a 70 48 69 77 74 72 ten into *pHiwtr
3a760 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 72 65 73 . If.** the res
3a770 65 74 46 6c 67 20 69 73 20 74 72 75 65 2c 20 74 etFlg is true, t
3a780 68 65 6e 20 74 68 65 20 68 69 67 68 65 73 74 20 hen the highest
3a790 69 6e 73 74 61 6e 74 61 6e 65 6f 75 73 20 76 61 instantaneous va
3a7a0 6c 75 65 20 69 73 0a 2a 2a 20 72 65 73 65 74 20 lue is.** reset
3a7b0 62 61 63 6b 20 64 6f 77 6e 20 74 6f 20 74 68 65 back down to the
3a7c0 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 2e 0a current value..
3a7d0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
3a7e0 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 [sqlite3_status(
3a7f0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
3a800 73 74 6d 74 5f 73 74 61 74 75 73 28 29 5d 2e 0a stmt_status()]..
3a810 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 */.SQLITE_API SQ
3a820 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 LITE_EXPERIMENTA
3a830 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 L int sqlite3_db
3a840 5f 73 74 61 74 75 73 28 73 71 6c 69 74 65 33 2a _status(sqlite3*
3a850 2c 20 69 6e 74 20 6f 70 2c 20 69 6e 74 20 2a 70 , int op, int *p
3a860 43 75 72 2c 20 69 6e 74 20 2a 70 48 69 77 74 72 Cur, int *pHiwtr
3a870 2c 20 69 6e 74 20 72 65 73 65 74 46 6c 67 29 3b , int resetFlg);
3a880 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
3a890 3a 20 53 74 61 74 75 73 20 50 61 72 61 6d 65 74 : Status Paramet
3a8a0 65 72 73 20 66 6f 72 20 64 61 74 61 62 61 73 65 ers for database
3a8b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 7b 48 31 connections {H1
3a8c0 37 35 32 30 7d 20 3c 48 31 37 35 30 30 3e 0a 2a 7520} <H17500>.*
3a8d0 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a * EXPERIMENTAL.*
3a8e0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 *.** These const
3a8f0 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 ants are the ava
3a900 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 22 ilable integer "
3a910 76 65 72 62 73 22 20 74 68 61 74 20 63 61 6e 20 verbs" that can
3a920 62 65 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 be passed as.**
3a930 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d the second argum
3a940 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 ent to the [sqli
3a950 74 65 33 5f 64 62 5f 73 74 61 74 75 73 28 29 5d te3_db_status()]
3a960 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a interface..**.*
3a970 2a 20 4e 65 77 20 76 65 72 62 73 20 6d 61 79 20 * New verbs may
3a980 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 be added in futu
3a990 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 re releases of S
3a9a0 51 4c 69 74 65 2e 20 45 78 69 73 74 69 6e 67 20 QLite. Existing
3a9b0 76 65 72 62 73 0a 2a 2a 20 6d 69 67 68 74 20 62 verbs.** might b
3a9c0 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 e discontinued.
3a9d0 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f Applications sho
3a9e0 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 uld check the re
3a9f0 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 0a 2a turn code from.*
3aa00 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 * [sqlite3_db_st
3aa10 61 74 75 73 28 29 5d 20 74 6f 20 6d 61 6b 65 20 atus()] to make
3aa20 73 75 72 65 20 74 68 61 74 20 74 68 65 20 63 61 sure that the ca
3aa30 6c 6c 20 77 6f 72 6b 65 64 2e 0a 2a 2a 20 54 68 ll worked..** Th
3aa40 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 e [sqlite3_db_st
3aa50 61 74 75 73 28 29 5d 20 69 6e 74 65 72 66 61 63 atus()] interfac
3aa60 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 20 e will return a
3aa70 6e 6f 6e 2d 7a 65 72 6f 20 65 72 72 6f 72 20 63 non-zero error c
3aa80 6f 64 65 0a 2a 2a 20 69 66 20 61 20 64 69 73 63 ode.** if a disc
3aa90 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 ontinued or unsu
3aaa0 70 70 6f 72 74 65 64 20 76 65 72 62 20 69 73 20 pported verb is
3aab0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c invoked..**.** <
3aac0 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 dl>.** <dt>SQLIT
3aad0 45 5f 44 42 53 54 41 54 55 53 5f 4c 4f 4f 4b 41 E_DBSTATUS_LOOKA
3aae0 53 49 44 45 5f 55 53 45 44 3c 2f 64 74 3e 0a 2a SIDE_USED</dt>.*
3aaf0 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d * <dd>This param
3ab00 65 74 65 72 20 72 65 74 75 72 6e 73 20 74 68 65 eter returns the
3ab10 20 6e 75 6d 62 65 72 20 6f 66 20 6c 6f 6f 6b 61 number of looka
3ab20 73 69 64 65 20 6d 65 6d 6f 72 79 20 73 6c 6f 74 side memory slot
3ab30 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 63 s currently.** c
3ab40 68 65 63 6b 65 64 20 6f 75 74 2e 3c 2f 64 64 3e hecked out.</dd>
3ab50 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 .** </dl>.*/.#de
3ab60 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 53 54 fine SQLITE_DBST
3ab70 41 54 55 53 5f 4c 4f 4f 4b 41 53 49 44 45 5f 55 ATUS_LOOKASIDE_U
3ab80 53 45 44 20 20 20 20 20 30 0a 0a 0a 2f 2a 0a 2a SED 0.../*.*
3ab90 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72 65 70 * CAPI3REF: Prep
3aba0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 53 ared Statement S
3abb0 74 61 74 75 73 20 7b 48 31 37 35 35 30 7d 20 3c tatus {H17550} <
3abc0 53 36 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 S60200>.** EXPER
3abd0 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 45 61 IMENTAL.**.** Ea
3abe0 63 68 20 70 72 65 70 61 72 65 64 20 73 74 61 74 ch prepared stat
3abf0 65 6d 65 6e 74 20 6d 61 69 6e 74 61 69 6e 73 20 ement maintains
3ac00 76 61 72 69 6f 75 73 0a 2a 2a 20 5b 53 51 4c 49 various.** [SQLI
3ac10 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f 53 4f TE_STMTSTATUS_SO
3ac20 52 54 20 7c 20 63 6f 75 6e 74 65 72 73 5d 20 74 RT | counters] t
3ac30 68 61 74 20 6d 65 61 73 75 72 65 20 74 68 65 20 hat measure the
3ac40 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 74 69 6d number.** of tim
3ac50 65 73 20 69 74 20 68 61 73 20 70 65 72 66 6f 72 es it has perfor
3ac60 6d 65 64 20 73 70 65 63 69 66 69 63 20 6f 70 65 med specific ope
3ac70 72 61 74 69 6f 6e 73 2e 20 20 54 68 65 73 65 20 rations. These
3ac80 63 6f 75 6e 74 65 72 73 20 63 61 6e 0a 2a 2a 20 counters can.**
3ac90 62 65 20 75 73 65 64 20 74 6f 20 6d 6f 6e 69 74 be used to monit
3aca0 6f 72 20 74 68 65 20 70 65 72 66 6f 72 6d 61 6e or the performan
3acb0 63 65 20 63 68 61 72 61 63 74 65 72 69 73 74 69 ce characteristi
3acc0 63 73 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 cs of the prepar
3acd0 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 ed.** statements
3ace0 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 . For example,
3acf0 69 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 if the number of
3ad00 20 74 61 62 6c 65 20 73 74 65 70 73 20 67 72 65 table steps gre
3ad10 61 74 6c 79 20 65 78 63 65 65 64 73 0a 2a 2a 20 atly exceeds.**
3ad20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 61 the number of ta
3ad30 62 6c 65 20 73 65 61 72 63 68 65 73 20 6f 72 20 ble searches or
3ad40 72 65 73 75 6c 74 20 72 6f 77 73 2c 20 74 68 61 result rows, tha
3ad50 74 20 77 6f 75 6c 64 20 74 65 6e 64 20 74 6f 20 t would tend to
3ad60 69 6e 64 69 63 61 74 65 0a 2a 2a 20 74 68 61 74 indicate.** that
3ad70 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 the prepared st
3ad80 61 74 65 6d 65 6e 74 20 69 73 20 75 73 69 6e 67 atement is using
3ad90 20 61 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 a full table sc
3ada0 61 6e 20 72 61 74 68 65 72 20 74 68 61 6e 0a 2a an rather than.*
3adb0 2a 20 61 6e 20 69 6e 64 65 78 2e 20 20 0a 2a 2a * an index. .**
3adc0 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 .** This interfa
3add0 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 ce is used to re
3ade0 74 72 69 65 76 65 20 61 6e 64 20 72 65 73 65 74 trieve and reset
3adf0 20 63 6f 75 6e 74 65 72 20 76 61 6c 75 65 73 20 counter values
3ae00 66 72 6f 6d 0a 2a 2a 20 61 20 5b 70 72 65 70 61 from.** a [prepa
3ae10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 red statement].
3ae20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
3ae30 65 6e 74 20 69 73 20 74 68 65 20 70 72 65 70 61 ent is the prepa
3ae40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a red statement.**
3ae50 20 6f 62 6a 65 63 74 20 74 6f 20 62 65 20 69 6e object to be in
3ae60 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 terrogated. The
3ae70 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
3ae80 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65 .** is an intege
3ae90 72 20 63 6f 64 65 20 66 6f 72 20 61 20 73 70 65 r code for a spe
3aea0 63 69 66 69 63 20 5b 53 51 4c 49 54 45 5f 53 54 cific [SQLITE_ST
3aeb0 4d 54 53 54 41 54 55 53 5f 53 4f 52 54 20 7c 20 MTSTATUS_SORT |
3aec0 63 6f 75 6e 74 65 72 5d 0a 2a 2a 20 74 6f 20 62 counter].** to b
3aed0 65 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 e interrogated.
3aee0 0a 2a 2a 20 54 68 65 20 63 75 72 72 65 6e 74 20 .** The current
3aef0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 72 65 71 value of the req
3af00 75 65 73 74 65 64 20 63 6f 75 6e 74 65 72 20 69 uested counter i
3af10 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 s returned..** I
3af20 66 20 74 68 65 20 72 65 73 65 74 46 6c 67 20 69 f the resetFlg i
3af30 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 s true, then the
3af40 20 63 6f 75 6e 74 65 72 20 69 73 20 72 65 73 65 counter is rese
3af50 74 20 74 6f 20 7a 65 72 6f 20 61 66 74 65 72 20 t to zero after
3af60 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 this.** interfac
3af70 65 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a e call returns..
3af80 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
3af90 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 [sqlite3_status(
3afa0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
3afb0 64 62 5f 73 74 61 74 75 73 28 29 5d 2e 0a 2a 2f db_status()]..*/
3afc0 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 .SQLITE_API SQLI
3afd0 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 TE_EXPERIMENTAL
3afe0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 int sqlite3_stmt
3aff0 5f 73 74 61 74 75 73 28 73 71 6c 69 74 65 33 5f _status(sqlite3_
3b000 73 74 6d 74 2a 2c 20 69 6e 74 20 6f 70 2c 69 6e stmt*, int op,in
3b010 74 20 72 65 73 65 74 46 6c 67 29 3b 0a 0a 2f 2a t resetFlg);../*
3b020 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 .** CAPI3REF: St
3b030 61 74 75 73 20 50 61 72 61 6d 65 74 65 72 73 20 atus Parameters
3b040 66 6f 72 20 70 72 65 70 61 72 65 64 20 73 74 61 for prepared sta
3b050 74 65 6d 65 6e 74 73 20 7b 48 31 37 35 37 30 7d tements {H17570}
3b060 20 3c 48 31 37 35 35 30 3e 0a 2a 2a 20 45 58 50 <H17550>.** EXP
3b070 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 ERIMENTAL.**.**
3b080 54 68 65 73 65 20 70 72 65 70 72 6f 63 65 73 73 These preprocess
3b090 6f 72 20 6d 61 63 72 6f 73 20 64 65 66 69 6e 65 or macros define
3b0a0 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 integer codes t
3b0b0 68 61 74 20 6e 61 6d 65 20 63 6f 75 6e 74 65 72 hat name counter
3b0c0 0a 2a 2a 20 76 61 6c 75 65 73 20 61 73 73 6f 63 .** values assoc
3b0d0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b iated with the [
3b0e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 73 74 61 sqlite3_stmt_sta
3b0f0 74 75 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 tus()] interface
3b100 2e 0a 2a 2a 20 54 68 65 20 6d 65 61 6e 69 6e 67 ..** The meaning
3b110 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 s of the various
3b120 20 63 6f 75 6e 74 65 72 73 20 61 72 65 20 61 73 counters are as
3b130 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 follows:.**.**
3b140 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 <dl>.** <dt>SQLI
3b150 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f 46 55 TE_STMTSTATUS_FU
3b160 4c 4c 53 43 41 4e 5f 53 54 45 50 3c 2f 64 74 3e LLSCAN_STEP</dt>
3b170 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 69 73 20 .** <dd>This is
3b180 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 the number of ti
3b190 6d 65 73 20 74 68 61 74 20 53 51 4c 69 74 65 20 mes that SQLite
3b1a0 68 61 73 20 73 74 65 70 70 65 64 20 66 6f 72 77 has stepped forw
3b1b0 61 72 64 20 69 6e 0a 2a 2a 20 61 20 74 61 62 6c ard in.** a tabl
3b1c0 65 20 61 73 20 70 61 72 74 20 6f 66 20 61 20 66 e as part of a f
3b1d0 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 2e 20 ull table scan.
3b1e0 20 4c 61 72 67 65 20 6e 75 6d 62 65 72 73 20 66 Large numbers f
3b1f0 6f 72 20 74 68 69 73 20 63 6f 75 6e 74 65 72 0a or this counter.
3b200 2a 2a 20 6d 61 79 20 69 6e 64 69 63 61 74 65 20 ** may indicate
3b210 6f 70 70 6f 72 74 75 6e 69 74 69 65 73 20 66 6f opportunities fo
3b220 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 69 6d r performance im
3b230 70 72 6f 76 65 6d 65 6e 74 20 74 68 72 6f 75 67 provement throug
3b240 68 20 0a 2a 2a 20 63 61 72 65 66 75 6c 20 75 73 h .** careful us
3b250 65 20 6f 66 20 69 6e 64 69 63 65 73 2e 3c 2f 64 e of indices.</d
3b260 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
3b270 49 54 45 5f 53 54 4d 54 53 54 41 54 55 53 5f 53 ITE_STMTSTATUS_S
3b280 4f 52 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ORT</dt>.** <dd>
3b290 54 68 69 73 20 69 73 20 74 68 65 20 6e 75 6d 62 This is the numb
3b2a0 65 72 20 6f 66 20 73 6f 72 74 20 6f 70 65 72 61 er of sort opera
3b2b0 74 69 6f 6e 73 20 74 68 61 74 20 68 61 76 65 20 tions that have
3b2c0 6f 63 63 75 72 72 65 64 2e 0a 2a 2a 20 41 20 6e occurred..** A n
3b2d0 6f 6e 2d 7a 65 72 6f 20 76 61 6c 75 65 20 69 6e on-zero value in
3b2e0 20 74 68 69 73 20 63 6f 75 6e 74 65 72 20 6d 61 this counter ma
3b2f0 79 20 69 6e 64 69 63 61 74 65 20 61 6e 20 6f 70 y indicate an op
3b300 70 6f 72 74 75 6e 69 74 79 20 74 6f 0a 2a 2a 20 portunity to.**
3b310 69 6d 70 72 6f 76 65 6d 65 6e 74 20 70 65 72 66 improvement perf
3b320 6f 72 6d 61 6e 63 65 20 74 68 72 6f 75 67 68 20 ormance through
3b330 63 61 72 65 66 75 6c 20 75 73 65 20 6f 66 20 69 careful use of i
3b340 6e 64 69 63 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a ndices.</dd>.**.
3b350 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 ** </dl>.*/.#def
3b360 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 4d 54 53 ine SQLITE_STMTS
3b370 54 41 54 55 53 5f 46 55 4c 4c 53 43 41 4e 5f 53 TATUS_FULLSCAN_S
3b380 54 45 50 20 20 20 20 20 31 0a 23 64 65 66 69 6e TEP 1.#defin
3b390 65 20 53 51 4c 49 54 45 5f 53 54 4d 54 53 54 41 e SQLITE_STMTSTA
3b3a0 54 55 53 5f 53 4f 52 54 20 20 20 20 20 20 20 20 TUS_SORT
3b3b0 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 2../*.** C
3b3c0 41 50 49 33 52 45 46 3a 20 43 75 73 74 6f 6d 20 API3REF: Custom
3b3d0 50 61 67 65 20 43 61 63 68 65 20 4f 62 6a 65 63 Page Cache Objec
3b3e0 74 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 t.** EXPERIMENTA
3b3f0 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 L.**.** The sqli
3b400 74 65 33 5f 70 63 61 63 68 65 20 74 79 70 65 20 te3_pcache type
3b410 69 73 20 6f 70 61 71 75 65 2e 20 20 49 74 20 69 is opaque. It i
3b420 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 s implemented by
3b430 0a 2a 2a 20 74 68 65 20 70 6c 75 67 67 61 62 6c .** the pluggabl
3b440 65 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 53 e module. The S
3b450 51 4c 69 74 65 20 63 6f 72 65 20 68 61 73 20 6e QLite core has n
3b460 6f 20 6b 6e 6f 77 6c 65 64 67 65 20 6f 66 0a 2a o knowledge of.*
3b470 2a 20 69 74 73 20 73 69 7a 65 20 6f 72 20 69 6e * its size or in
3b480 74 65 72 6e 61 6c 20 73 74 72 75 63 74 75 72 65 ternal structure
3b490 20 61 6e 64 20 6e 65 76 65 72 20 64 65 61 6c 73 and never deals
3b4a0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 73 71 6c with the.** sql
3b4b0 69 74 65 33 5f 70 63 61 63 68 65 20 6f 62 6a 65 ite3_pcache obje
3b4c0 63 74 20 65 78 63 65 70 74 20 62 79 20 68 6f 6c ct except by hol
3b4d0 64 69 6e 67 20 61 6e 64 20 70 61 73 73 69 6e 67 ding and passing
3b4e0 20 70 6f 69 6e 74 65 72 73 0a 2a 2a 20 74 6f 20 pointers.** to
3b4f0 74 68 65 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a the object..**.*
3b500 2a 20 53 65 65 20 5b 73 71 6c 69 74 65 33 5f 70 * See [sqlite3_p
3b510 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 66 cache_methods] f
3b520 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e or additional in
3b530 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 formation..*/.ty
3b540 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
3b550 69 74 65 33 5f 70 63 61 63 68 65 20 73 71 6c 69 ite3_pcache sqli
3b560 74 65 33 5f 70 63 61 63 68 65 3b 0a 0a 2f 2a 0a te3_pcache;../*.
3b570 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 70 70 ** CAPI3REF: App
3b580 6c 69 63 61 74 69 6f 6e 20 44 65 66 69 6e 65 64 lication Defined
3b590 20 50 61 67 65 20 43 61 63 68 65 2e 0a 2a 2a 20 Page Cache..**
3b5a0 4b 45 59 57 4f 52 44 53 3a 20 7b 70 61 67 65 20 KEYWORDS: {page
3b5b0 63 61 63 68 65 7d 0a 2a 2a 20 45 58 50 45 52 49 cache}.** EXPERI
3b5c0 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 MENTAL.**.** The
3b5d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
3b5e0 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ]([SQLITE_CONFIG
3b5f0 5f 50 43 41 43 48 45 5d 2c 20 2e 2e 2e 29 20 69 _PCACHE], ...) i
3b600 6e 74 65 72 66 61 63 65 20 63 61 6e 0a 2a 2a 20 nterface can.**
3b610 72 65 67 69 73 74 65 72 20 61 6e 20 61 6c 74 65 register an alte
3b620 72 6e 61 74 69 76 65 20 70 61 67 65 20 63 61 63 rnative page cac
3b630 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
3b640 6e 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 n by passing in
3b650 61 6e 20 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 an .** instance
3b660 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 of the sqlite3_p
3b670 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 20 73 74 cache_methods st
3b680 72 75 63 74 75 72 65 2e 20 54 68 65 20 6d 61 6a ructure. The maj
3b690 6f 72 69 74 79 20 6f 66 20 74 68 65 20 0a 2a 2a ority of the .**
3b6a0 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 75 73 65 heap memory use
3b6b0 64 20 62 79 20 53 51 4c 69 74 65 20 69 73 20 75 d by SQLite is u
3b6c0 73 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20 sed by the page
3b6d0 63 61 63 68 65 20 74 6f 20 63 61 63 68 65 20 64 cache to cache d
3b6e0 61 74 61 20 72 65 61 64 20 0a 2a 2a 20 66 72 6f ata read .** fro
3b6f0 6d 2c 20 6f 72 20 72 65 61 64 79 20 74 6f 20 62 m, or ready to b
3b700 65 20 77 72 69 74 74 65 6e 20 74 6f 2c 20 74 68 e written to, th
3b710 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e e database file.
3b720 20 42 79 20 69 6d 70 6c 65 6d 65 6e 74 69 6e 67 By implementing
3b730 20 61 20 0a 2a 2a 20 63 75 73 74 6f 6d 20 70 61 a .** custom pa
3b740 67 65 20 63 61 63 68 65 20 75 73 69 6e 67 20 74 ge cache using t
3b750 68 69 73 20 41 50 49 2c 20 61 6e 20 61 70 70 6c his API, an appl
3b760 69 63 61 74 69 6f 6e 20 63 61 6e 20 63 6f 6e 74 ication can cont
3b770 72 6f 6c 20 6d 6f 72 65 20 0a 2a 2a 20 70 72 65 rol more .** pre
3b780 63 69 73 65 6c 79 20 74 68 65 20 61 6d 6f 75 6e cisely the amoun
3b790 74 20 6f 66 20 6d 65 6d 6f 72 79 20 63 6f 6e 73 t of memory cons
3b7a0 75 6d 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 umed by SQLite,
3b7b0 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 the way in which
3b7c0 20 0a 2a 2a 20 74 68 61 74 20 6d 65 6d 6f 72 79 .** that memory
3b7d0 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e is allocated an
3b7e0 64 20 72 65 6c 65 61 73 65 64 2c 20 61 6e 64 20 d released, and
3b7f0 74 68 65 20 70 6f 6c 69 63 69 65 73 20 75 73 65 the policies use
3b800 64 20 74 6f 20 0a 2a 2a 20 64 65 74 65 72 6d 69 d to .** determi
3b810 6e 65 20 65 78 61 63 74 6c 79 20 77 68 69 63 68 ne exactly which
3b820 20 70 61 72 74 73 20 6f 66 20 61 20 64 61 74 61 parts of a data
3b830 62 61 73 65 20 66 69 6c 65 20 61 72 65 20 63 61 base file are ca
3b840 63 68 65 64 20 61 6e 64 20 66 6f 72 20 0a 2a 2a ched and for .**
3b850 20 68 6f 77 20 6c 6f 6e 67 2e 0a 2a 2a 0a 2a 2a how long..**.**
3b860 20 54 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 The contents of
3b870 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 63 61 the sqlite3_pca
3b880 63 68 65 5f 6d 65 74 68 6f 64 73 20 73 74 72 75 che_methods stru
3b890 63 74 75 72 65 20 61 72 65 20 63 6f 70 69 65 64 cture are copied
3b8a0 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 74 65 72 6e to an.** intern
3b8b0 61 6c 20 62 75 66 66 65 72 20 62 79 20 53 51 4c al buffer by SQL
3b8c0 69 74 65 20 77 69 74 68 69 6e 20 74 68 65 20 63 ite within the c
3b8d0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
3b8e0 63 6f 6e 66 69 67 5d 2e 20 20 48 65 6e 63 65 0a config]. Hence.
3b8f0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ** the applicati
3b900 6f 6e 20 6d 61 79 20 64 69 73 63 61 72 64 20 74 on may discard t
3b910 68 65 20 70 61 72 61 6d 65 74 65 72 20 61 66 74 he parameter aft
3b920 65 72 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a er the call to.*
3b930 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 * [sqlite3_confi
3b940 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 0a 2a 2a g()] returns..**
3b950 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 28 29 20 .** The xInit()
3b960 6d 65 74 68 6f 64 20 69 73 20 63 61 6c 6c 65 64 method is called
3b970 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 63 once for each c
3b980 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
3b990 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 0a 2a 2a initialize()].**
3b9a0 20 28 75 73 75 61 6c 6c 79 20 6f 6e 6c 79 20 6f (usually only o
3b9b0 6e 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 6c nce during the l
3b9c0 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20 70 ifetime of the p
3b9d0 72 6f 63 65 73 73 29 2e 20 49 74 20 69 73 20 70 rocess). It is p
3b9e0 61 73 73 65 64 0a 2a 2a 20 61 20 63 6f 70 79 20 assed.** a copy
3b9f0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 of the sqlite3_p
3ba00 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2e 70 41 cache_methods.pA
3ba10 72 67 20 76 61 6c 75 65 2e 20 49 74 20 63 61 6e rg value. It can
3ba20 20 62 65 20 75 73 65 64 20 74 6f 20 73 65 74 0a be used to set.
3ba30 2a 2a 20 75 70 20 67 6c 6f 62 61 6c 20 73 74 72 ** up global str
3ba40 75 63 74 75 72 65 73 20 61 6e 64 20 6d 75 74 65 uctures and mute
3ba50 78 65 73 20 72 65 71 75 69 72 65 64 20 62 79 20 xes required by
3ba60 74 68 65 20 63 75 73 74 6f 6d 20 70 61 67 65 20 the custom page
3ba70 63 61 63 68 65 20 0a 2a 2a 20 69 6d 70 6c 65 6d cache .** implem
3ba80 65 6e 74 61 74 69 6f 6e 2e 20 0a 2a 2a 0a 2a 2a entation. .**.**
3ba90 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 28 29 The xShutdown()
3baa0 20 6d 65 74 68 6f 64 20 69 73 20 63 61 6c 6c 65 method is calle
3bab0 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 5b 73 d from within [s
3bac0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
3bad0 29 5d 2c 20 0a 2a 2a 20 69 66 20 74 68 65 20 61 )], .** if the a
3bae0 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 76 6f 6b pplication invok
3baf0 65 73 20 74 68 69 73 20 41 50 49 2e 20 49 74 20 es this API. It
3bb00 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 can be used to c
3bb10 6c 65 61 6e 20 75 70 20 0a 2a 2a 20 61 6e 79 20 lean up .** any
3bb20 6f 75 74 73 74 61 6e 64 69 6e 67 20 72 65 73 6f outstanding reso
3bb30 75 72 63 65 73 20 62 65 66 6f 72 65 20 70 72 6f urces before pro
3bb40 63 65 73 73 20 73 68 75 74 64 6f 77 6e 2c 20 69 cess shutdown, i
3bb50 66 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a f required..**.*
3bb60 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 61 * SQLite holds a
3bb70 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 [SQLITE_MUTEX_R
3bb80 45 43 55 52 53 49 56 45 5d 20 6d 75 74 65 78 20 ECURSIVE] mutex
3bb90 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a when it invokes.
3bba0 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 ** the xInit met
3bbb0 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 hod, so the xIni
3bbc0 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f t method need no
3bbd0 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e t be threadsafe.
3bbe0 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f The.** xShutdo
3bbf0 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c wn method is onl
3bc00 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 y called from [s
3bc10 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
3bc20 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a )] so it does.**
3bc30 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 not need to be
3bc40 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65 threadsafe eithe
3bc50 72 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 6d 65 r. All other me
3bc60 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 thods must be th
3bc70 72 65 61 64 73 61 66 65 0a 2a 2a 20 69 6e 20 6d readsafe.** in m
3bc80 75 6c 74 69 74 68 72 65 61 64 65 64 20 61 70 70 ultithreaded app
3bc90 6c 69 63 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a lications..**.**
3bca0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 SQLite will nev
3bcb0 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 er invoke xInit(
3bcc0 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 ) more than once
3bcd0 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 without an inte
3bce0 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 rvening.** call
3bcf0 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a to xShutdown()..
3bd00 2a 2a 0a 2a 2a 20 54 68 65 20 78 43 72 65 61 74 **.** The xCreat
3bd10 65 28 29 20 6d 65 74 68 6f 64 20 69 73 20 75 73 e() method is us
3bd20 65 64 20 74 6f 20 63 6f 6e 73 74 72 75 63 74 20 ed to construct
3bd30 61 20 6e 65 77 20 63 61 63 68 65 20 69 6e 73 74 a new cache inst
3bd40 61 6e 63 65 2e 20 20 53 51 4c 69 74 65 0a 2a 2a ance. SQLite.**
3bd50 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 will typically
3bd60 63 72 65 61 74 65 20 6f 6e 65 20 63 61 63 68 65 create one cache
3bd70 20 69 6e 73 74 61 6e 63 65 20 66 6f 72 20 65 61 instance for ea
3bd80 63 68 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 ch open database
3bd90 20 66 69 6c 65 2c 0a 2a 2a 20 74 68 6f 75 67 68 file,.** though
3bda0 20 74 68 69 73 20 69 73 20 6e 6f 74 20 67 75 61 this is not gua
3bdb0 72 61 6e 74 65 65 64 2e 20 54 68 65 0a 2a 2a 20 ranteed. The.**
3bdc0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2c first parameter,
3bdd0 20 73 7a 50 61 67 65 2c 20 69 73 20 74 68 65 20 szPage, is the
3bde0 73 69 7a 65 20 69 6e 20 62 79 74 65 73 20 6f 66 size in bytes of
3bdf0 20 74 68 65 20 70 61 67 65 73 20 74 68 61 74 20 the pages that
3be00 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 6c 6f 63 must.** be alloc
3be10 61 74 65 64 20 62 79 20 74 68 65 20 63 61 63 68 ated by the cach
3be20 65 2e 20 20 73 7a 50 61 67 65 20 77 69 6c 6c 20 e. szPage will
3be30 6e 6f 74 20 62 65 20 61 20 70 6f 77 65 72 20 6f not be a power o
3be40 66 20 74 77 6f 2e 20 20 73 7a 50 61 67 65 0a 2a f two. szPage.*
3be50 2a 20 77 69 6c 6c 20 74 68 65 20 70 61 67 65 20 * will the page
3be60 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 size of the data
3be70 62 61 73 65 20 66 69 6c 65 20 74 68 61 74 20 69 base file that i
3be80 73 20 74 6f 20 62 65 20 63 61 63 68 65 64 20 70 s to be cached p
3be90 6c 75 73 20 61 6e 0a 2a 2a 20 69 6e 63 72 65 6d lus an.** increm
3bea0 65 6e 74 20 28 68 65 72 65 20 63 61 6c 6c 65 64 ent (here called
3beb0 20 22 52 22 29 20 6f 66 20 61 62 6f 75 74 20 31 "R") of about 1
3bec0 30 30 20 6f 72 20 32 30 30 2e 20 20 53 51 4c 69 00 or 200. SQLi
3bed0 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 0a te will use the.
3bee0 2a 2a 20 65 78 74 72 61 20 52 20 62 79 74 65 73 ** extra R bytes
3bef0 20 6f 6e 20 65 61 63 68 20 70 61 67 65 20 74 6f on each page to
3bf00 20 73 74 6f 72 65 20 6d 65 74 61 64 61 74 61 20 store metadata
3bf10 61 62 6f 75 74 20 74 68 65 20 75 6e 64 65 72 6c about the underl
3bf20 79 69 6e 67 0a 2a 2a 20 64 61 74 61 62 61 73 65 ying.** database
3bf30 20 70 61 67 65 20 6f 6e 20 64 69 73 6b 2e 20 20 page on disk.
3bf40 54 68 65 20 76 61 6c 75 65 20 6f 66 20 52 20 64 The value of R d
3bf50 65 70 65 6e 64 73 0a 2a 2a 20 6f 6e 20 74 68 65 epends.** on the
3bf60 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2c SQLite version,
3bf70 20 74 68 65 20 74 61 72 67 65 74 20 70 6c 61 74 the target plat
3bf80 66 6f 72 6d 2c 20 61 6e 64 20 68 6f 77 20 53 51 form, and how SQ
3bf90 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69 6c 65 Lite was compile
3bfa0 64 2e 0a 2a 2a 20 52 20 69 73 20 63 6f 6e 73 74 d..** R is const
3bfb0 61 6e 74 20 66 6f 72 20 61 20 70 61 72 74 69 63 ant for a partic
3bfc0 75 6c 61 72 20 62 75 69 6c 64 20 6f 66 20 53 51 ular build of SQ
3bfd0 4c 69 74 65 2e 20 20 54 68 65 20 73 65 63 6f 6e Lite. The secon
3bfe0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a d argument to.**
3bff0 20 78 43 72 65 61 74 65 28 29 2c 20 62 50 75 72 xCreate(), bPur
3c000 67 65 61 62 6c 65 2c 20 69 73 20 74 72 75 65 20 geable, is true
3c010 69 66 20 74 68 65 20 63 61 63 68 65 20 62 65 69 if the cache bei
3c020 6e 67 20 63 72 65 61 74 65 64 20 77 69 6c 6c 0a ng created will.
3c030 2a 2a 20 62 65 20 75 73 65 64 20 74 6f 20 63 61 ** be used to ca
3c040 63 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 che database pag
3c050 65 73 20 6f 66 20 61 20 66 69 6c 65 20 73 74 6f es of a file sto
3c060 72 65 64 20 6f 6e 20 64 69 73 6b 2c 20 6f 72 0a red on disk, or.
3c070 2a 2a 20 66 61 6c 73 65 20 69 66 20 69 74 20 69 ** false if it i
3c080 73 20 75 73 65 64 20 66 6f 72 20 61 6e 20 69 6e s used for an in
3c090 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 -memory database
3c0a0 2e 20 54 68 65 20 63 61 63 68 65 20 69 6d 70 6c . The cache impl
3c0b0 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 64 6f ementation.** do
3c0c0 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 20 64 es not have to d
3c0d0 6f 20 61 6e 79 74 68 69 6e 67 20 73 70 65 63 69 o anything speci
3c0e0 61 6c 20 62 61 73 65 64 20 77 69 74 68 20 74 68 al based with th
3c0f0 65 20 76 61 6c 75 65 20 6f 66 20 62 50 75 72 67 e value of bPurg
3c100 65 61 62 6c 65 3b 0a 2a 2a 20 69 74 20 69 73 20 eable;.** it is
3c110 70 75 72 65 6c 79 20 61 64 76 69 73 6f 72 79 2e purely advisory.
3c120 20 20 4f 6e 20 61 20 63 61 63 68 65 20 77 68 65 On a cache whe
3c130 72 65 20 62 50 75 72 67 65 61 62 6c 65 20 69 73 re bPurgeable is
3c140 20 66 61 6c 73 65 2c 20 53 51 4c 69 74 65 20 77 false, SQLite w
3c150 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 69 6e 76 ill.** never inv
3c160 6f 6b 65 20 78 55 6e 70 69 6e 28 29 20 65 78 63 oke xUnpin() exc
3c170 65 70 74 20 74 6f 20 64 65 6c 69 62 65 72 61 74 ept to deliberat
3c180 65 6c 79 20 64 65 6c 65 74 65 20 61 20 70 61 67 ely delete a pag
3c190 65 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 e..** In other w
3c1a0 6f 72 64 73 2c 20 61 20 63 61 63 68 65 20 63 72 ords, a cache cr
3c1b0 65 61 74 65 64 20 77 69 74 68 20 62 50 75 72 67 eated with bPurg
3c1c0 65 61 62 6c 65 20 73 65 74 20 74 6f 20 66 61 6c eable set to fal
3c1d0 73 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72 se will.** never
3c1e0 20 63 6f 6e 74 61 69 6e 20 61 6e 79 20 75 6e 70 contain any unp
3c1f0 69 6e 6e 65 64 20 70 61 67 65 73 2e 0a 2a 2a 0a inned pages..**.
3c200 2a 2a 20 54 68 65 20 78 43 61 63 68 65 73 69 7a ** The xCachesiz
3c210 65 28 29 20 6d 65 74 68 6f 64 20 6d 61 79 20 62 e() method may b
3c220 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 e called at any
3c230 74 69 6d 65 20 62 79 20 53 51 4c 69 74 65 20 74 time by SQLite t
3c240 6f 20 73 65 74 20 74 68 65 0a 2a 2a 20 73 75 67 o set the.** sug
3c250 67 65 73 74 65 64 20 6d 61 78 69 6d 75 6d 20 63 gested maximum c
3c260 61 63 68 65 2d 73 69 7a 65 20 28 6e 75 6d 62 65 ache-size (numbe
3c270 72 20 6f 66 20 70 61 67 65 73 20 73 74 6f 72 65 r of pages store
3c280 64 20 62 79 29 20 74 68 65 20 63 61 63 68 65 0a d by) the cache.
3c290 2a 2a 20 69 6e 73 74 61 6e 63 65 20 70 61 73 73 ** instance pass
3c2a0 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 ed as the first
3c2b0 61 72 67 75 6d 65 6e 74 2e 20 54 68 69 73 20 69 argument. This i
3c2c0 73 20 74 68 65 20 76 61 6c 75 65 20 63 6f 6e 66 s the value conf
3c2d0 69 67 75 72 65 64 20 75 73 69 6e 67 0a 2a 2a 20 igured using.**
3c2e0 74 68 65 20 53 51 4c 69 74 65 20 22 5b 50 52 41 the SQLite "[PRA
3c2f0 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 22 GMA cache_size]"
3c300 20 63 6f 6d 6d 61 6e 64 2e 20 41 73 20 77 69 74 command. As wit
3c310 68 20 74 68 65 20 62 50 75 72 67 65 61 62 6c 65 h the bPurgeable
3c320 20 70 61 72 61 6d 65 74 65 72 2c 0a 2a 2a 20 74 parameter,.** t
3c330 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
3c340 6e 20 69 73 20 6e 6f 74 20 72 65 71 75 69 72 65 n is not require
3c350 64 20 74 6f 20 64 6f 20 61 6e 79 74 68 69 6e 67 d to do anything
3c360 20 77 69 74 68 20 74 68 69 73 0a 2a 2a 20 76 61 with this.** va
3c370 6c 75 65 3b 20 69 74 20 69 73 20 61 64 76 69 73 lue; it is advis
3c380 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 ory only..**.**
3c390 54 68 65 20 78 50 61 67 65 63 6f 75 6e 74 28 29 The xPagecount()
3c3a0 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 72 method should r
3c3b0 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 eturn the number
3c3c0 20 6f 66 20 70 61 67 65 73 20 63 75 72 72 65 6e of pages curren
3c3d0 74 6c 79 0a 2a 2a 20 73 74 6f 72 65 64 20 69 6e tly.** stored in
3c3e0 20 74 68 65 20 63 61 63 68 65 2e 0a 2a 2a 20 0a the cache..** .
3c3f0 2a 2a 20 54 68 65 20 78 46 65 74 63 68 28 29 20 ** The xFetch()
3c400 6d 65 74 68 6f 64 20 69 73 20 75 73 65 64 20 74 method is used t
3c410 6f 20 66 65 74 63 68 20 61 20 70 61 67 65 20 61 o fetch a page a
3c420 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e nd return a poin
3c430 74 65 72 20 74 6f 20 69 74 2e 20 0a 2a 2a 20 41 ter to it. .** A
3c440 20 27 70 61 67 65 27 2c 20 69 6e 20 74 68 69 73 'page', in this
3c450 20 63 6f 6e 74 65 78 74 2c 20 69 73 20 61 20 62 context, is a b
3c460 75 66 66 65 72 20 6f 66 20 73 7a 50 61 67 65 20 uffer of szPage
3c470 62 79 74 65 73 20 61 6c 69 67 6e 65 64 20 61 74 bytes aligned at
3c480 20 61 6e 0a 2a 2a 20 38 2d 62 79 74 65 20 62 6f an.** 8-byte bo
3c490 75 6e 64 61 72 79 2e 20 54 68 65 20 70 61 67 65 undary. The page
3c4a0 20 74 6f 20 62 65 20 66 65 74 63 68 65 64 20 69 to be fetched i
3c4b0 73 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 s determined by
3c4c0 74 68 65 20 6b 65 79 2e 20 54 68 65 0a 2a 2a 20 the key. The.**
3c4d0 6d 69 6d 69 6d 75 6d 20 6b 65 79 20 76 61 6c 75 mimimum key valu
3c4e0 65 20 69 73 20 31 2e 20 41 66 74 65 72 20 69 74 e is 1. After it
3c4f0 20 68 61 73 20 62 65 65 6e 20 72 65 74 72 69 65 has been retrie
3c500 76 65 64 20 75 73 69 6e 67 20 78 46 65 74 63 68 ved using xFetch
3c510 2c 20 74 68 65 20 70 61 67 65 20 0a 2a 2a 20 69 , the page .** i
3c520 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 s considered to
3c530 62 65 20 22 70 69 6e 6e 65 64 22 2e 0a 2a 2a 0a be "pinned"..**.
3c540 2a 2a 20 49 66 20 74 68 65 20 72 65 71 75 65 73 ** If the reques
3c550 74 65 64 20 70 61 67 65 20 69 73 20 61 6c 72 65 ted page is alre
3c560 61 64 79 20 69 6e 20 74 68 65 20 70 61 67 65 20 ady in the page
3c570 63 61 63 68 65 2c 20 74 68 65 6e 20 74 68 65 20 cache, then the
3c580 70 61 67 65 20 63 61 63 68 65 0a 2a 2a 20 69 6d page cache.** im
3c590 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 plementation mus
3c5a0 74 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 t return a point
3c5b0 65 72 20 74 6f 20 74 68 65 20 70 61 67 65 20 62 er to the page b
3c5c0 75 66 66 65 72 20 77 69 74 68 20 69 74 73 20 63 uffer with its c
3c5d0 6f 6e 74 65 6e 74 0a 2a 2a 20 69 6e 74 61 63 74 ontent.** intact
3c5e0 2e 20 20 49 66 20 74 68 65 20 72 65 71 75 65 73 . If the reques
3c5f0 74 65 64 20 70 61 67 65 20 69 73 20 6e 6f 74 20 ted page is not
3c600 61 6c 72 65 61 64 79 20 69 6e 20 74 68 65 20 63 already in the c
3c610 61 63 68 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a ache, then the.*
3c620 2a 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 * behavior of th
3c630 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e e cache implemen
3c640 74 61 74 69 6f 6e 20 69 73 20 64 65 74 65 72 6d tation is determ
3c650 69 6e 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 ined by the valu
3c660 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 72 65 61 e of the.** crea
3c670 74 65 46 6c 61 67 20 70 61 72 61 6d 65 74 65 72 teFlag parameter
3c680 20 70 61 73 73 65 64 20 74 6f 20 78 46 65 74 63 passed to xFetc
3c690 68 2c 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 h, according to
3c6a0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 the following ta
3c6b0 62 6c 65 3a 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c ble:.**.** <tabl
3c6c0 65 20 62 6f 72 64 65 72 3d 31 20 77 69 64 74 68 e border=1 width
3c6d0 3d 38 35 25 20 61 6c 69 67 6e 3d 63 65 6e 74 65 =85% align=cente
3c6e0 72 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 63 r>.** <tr><th> c
3c6f0 72 65 61 74 65 46 6c 61 67 20 3c 74 68 3e 20 42 reateFlag <th> B
3c700 65 68 61 76 69 6f 75 72 20 77 68 65 6e 20 70 61 ehaviour when pa
3c710 67 65 20 69 73 20 6e 6f 74 20 61 6c 72 65 61 64 ge is not alread
3c720 79 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20 3c 74 y in cache.** <t
3c730 72 3e 3c 74 64 3e 20 30 20 3c 74 64 3e 20 44 6f r><td> 0 <td> Do
3c740 20 6e 6f 74 20 61 6c 6c 6f 63 61 74 65 20 61 20 not allocate a
3c750 6e 65 77 20 70 61 67 65 2e 20 20 52 65 74 75 72 new page. Retur
3c760 6e 20 4e 55 4c 4c 2e 0a 2a 2a 20 3c 74 72 3e 3c n NULL..** <tr><
3c770 74 64 3e 20 31 20 3c 74 64 3e 20 41 6c 6c 6f 63 td> 1 <td> Alloc
3c780 61 74 65 20 61 20 6e 65 77 20 70 61 67 65 20 69 ate a new page i
3c790 66 20 69 74 20 65 61 73 79 20 61 6e 64 20 63 6f f it easy and co
3c7a0 6e 76 65 6e 69 65 6e 74 20 74 6f 20 64 6f 20 73 nvenient to do s
3c7b0 6f 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 o..**
3c7c0 20 20 20 20 20 20 4f 74 68 65 72 77 69 73 65 20 Otherwise
3c7d0 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a 20 return NULL..**
3c7e0 3c 74 72 3e 3c 74 64 3e 20 32 20 3c 74 64 3e 20 <tr><td> 2 <td>
3c7f0 4d 61 6b 65 20 65 76 65 72 79 20 65 66 66 6f 72 Make every effor
3c800 74 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 t to allocate a
3c810 6e 65 77 20 70 61 67 65 2e 20 20 4f 6e 6c 79 20 new page. Only
3c820 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 return.**
3c830 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 69 NULL i
3c840 66 20 61 6c 6c 6f 63 61 74 69 6e 67 20 61 20 6e f allocating a n
3c850 65 77 20 70 61 67 65 20 69 73 20 65 66 66 65 63 ew page is effec
3c860 74 69 76 65 6c 79 20 69 6d 70 6f 73 73 69 62 6c tively impossibl
3c870 65 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a e..** </table>.*
3c880 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c *.** SQLite will
3c890 20 6e 6f 72 6d 61 6c 6c 79 20 69 6e 76 6f 6b 65 normally invoke
3c8a0 20 78 46 65 74 63 68 28 29 20 77 69 74 68 20 61 xFetch() with a
3c8b0 20 63 72 65 61 74 65 46 6c 61 67 20 6f 66 20 30 createFlag of 0
3c8c0 20 6f 72 20 31 2e 20 20 49 66 0a 2a 2a 20 61 20 or 1. If.** a
3c8d0 63 61 6c 6c 20 74 6f 20 78 46 65 74 63 68 28 29 call to xFetch()
3c8e0 20 77 69 74 68 20 63 72 65 61 74 65 46 6c 61 67 with createFlag
3c8f0 3d 3d 31 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c ==1 returns NULL
3c900 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 77 69 , then SQLite wi
3c910 6c 6c 0a 2a 2a 20 61 74 74 65 6d 70 74 20 74 6f ll.** attempt to
3c920 20 75 6e 70 69 6e 20 6f 6e 65 20 6f 72 20 6d 6f unpin one or mo
3c930 72 65 20 63 61 63 68 65 20 70 61 67 65 73 20 62 re cache pages b
3c940 79 20 73 70 69 6c 6c 69 6e 67 20 74 68 65 20 63 y spilling the c
3c950 6f 6e 74 65 6e 74 20 6f 66 0a 2a 2a 20 70 69 6e ontent of.** pin
3c960 6e 65 64 20 70 61 67 65 73 20 74 6f 20 64 69 73 ned pages to dis
3c970 6b 20 61 6e 64 20 73 79 6e 63 68 69 6e 67 20 74 k and synching t
3c980 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 he operating sys
3c990 74 65 6d 20 64 69 73 6b 20 63 61 63 68 65 2e 20 tem disk cache.
3c9a0 41 66 74 65 72 0a 2a 2a 20 61 74 74 65 6d 70 74 After.** attempt
3c9b0 69 6e 67 20 74 6f 20 75 6e 70 69 6e 20 70 61 67 ing to unpin pag
3c9c0 65 73 2c 20 74 68 65 20 78 46 65 74 63 68 28 29 es, the xFetch()
3c9d0 20 6d 65 74 68 6f 64 20 77 69 6c 6c 20 62 65 20 method will be
3c9e0 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e 20 77 69 invoked again wi
3c9f0 74 68 0a 2a 2a 20 61 20 63 72 65 61 74 65 46 6c th.** a createFl
3ca00 61 67 20 6f 66 20 32 2e 0a 2a 2a 0a 2a 2a 20 78 ag of 2..**.** x
3ca10 55 6e 70 69 6e 28 29 20 69 73 20 63 61 6c 6c 65 Unpin() is calle
3ca20 64 20 62 79 20 53 51 4c 69 74 65 20 77 69 74 68 d by SQLite with
3ca30 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
3ca40 63 75 72 72 65 6e 74 6c 79 20 70 69 6e 6e 65 64 currently pinned
3ca50 20 70 61 67 65 0a 2a 2a 20 61 73 20 69 74 73 20 page.** as its
3ca60 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e second argument.
3ca70 20 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 If the third pa
3ca80 72 61 6d 65 74 65 72 2c 20 64 69 73 63 61 72 64 rameter, discard
3ca90 2c 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a , is non-zero,.*
3caa0 2a 20 74 68 65 6e 20 74 68 65 20 70 61 67 65 20 * then the page
3cab0 73 68 6f 75 6c 64 20 62 65 20 65 76 69 63 74 65 should be evicte
3cac0 64 20 66 72 6f 6d 20 74 68 65 20 63 61 63 68 65 d from the cache
3cad0 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 20 53 . In this case S
3cae0 51 4c 69 74 65 20 0a 2a 2a 20 61 73 73 75 6d 65 QLite .** assume
3caf0 73 20 74 68 61 74 20 74 68 65 20 6e 65 78 74 20 s that the next
3cb00 74 69 6d 65 20 74 68 65 20 70 61 67 65 20 69 73 time the page is
3cb10 20 72 65 74 72 69 65 76 65 64 20 66 72 6f 6d 20 retrieved from
3cb20 74 68 65 20 63 61 63 68 65 20 75 73 69 6e 67 0a the cache using.
3cb30 2a 2a 20 74 68 65 20 78 46 65 74 63 68 28 29 20 ** the xFetch()
3cb40 6d 65 74 68 6f 64 2c 20 69 74 20 77 69 6c 6c 20 method, it will
3cb50 62 65 20 7a 65 72 6f 65 64 2e 20 49 66 20 74 68 be zeroed. If th
3cb60 65 20 64 69 73 63 61 72 64 20 70 61 72 61 6d 65 e discard parame
3cb70 74 65 72 20 69 73 0a 2a 2a 20 7a 65 72 6f 2c 20 ter is.** zero,
3cb80 74 68 65 6e 20 74 68 65 20 70 61 67 65 20 69 73 then the page is
3cb90 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 considered to b
3cba0 65 20 75 6e 70 69 6e 6e 65 64 2e 20 54 68 65 20 e unpinned. The
3cbb0 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 cache implementa
3cbc0 74 69 6f 6e 0a 2a 2a 20 6d 61 79 20 63 68 6f 6f tion.** may choo
3cbd0 73 65 20 74 6f 20 65 76 69 63 74 20 75 6e 70 69 se to evict unpi
3cbe0 6e 6e 65 64 20 70 61 67 65 73 20 61 74 20 61 6e nned pages at an
3cbf0 79 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 y time..**.** Th
3cc00 65 20 63 61 63 68 65 20 69 73 20 6e 6f 74 20 72 e cache is not r
3cc10 65 71 75 69 72 65 64 20 74 6f 20 70 65 72 66 6f equired to perfo
3cc20 72 6d 20 61 6e 79 20 72 65 66 65 72 65 6e 63 65 rm any reference
3cc30 20 63 6f 75 6e 74 69 6e 67 2e 20 41 20 73 69 6e counting. A sin
3cc40 67 6c 65 20 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 gle .** call to
3cc50 78 55 6e 70 69 6e 28 29 20 75 6e 70 69 6e 73 20 xUnpin() unpins
3cc60 74 68 65 20 70 61 67 65 20 72 65 67 61 72 64 6c the page regardl
3cc70 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 ess of the numbe
3cc80 72 20 6f 66 20 70 72 69 6f 72 20 63 61 6c 6c 73 r of prior calls
3cc90 20 0a 2a 2a 20 74 6f 20 78 46 65 74 63 68 28 29 .** to xFetch()
3cca0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 65 6b ..**.** The xRek
3ccb0 65 79 28 29 20 6d 65 74 68 6f 64 20 69 73 20 75 ey() method is u
3ccc0 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 sed to change th
3ccd0 65 20 6b 65 79 20 76 61 6c 75 65 20 61 73 73 6f e key value asso
3cce0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 0a ciated with the.
3ccf0 2a 2a 20 70 61 67 65 20 70 61 73 73 65 64 20 61 ** page passed a
3cd00 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 s the second arg
3cd10 75 6d 65 6e 74 20 66 72 6f 6d 20 6f 6c 64 4b 65 ument from oldKe
3cd20 79 20 74 6f 20 6e 65 77 4b 65 79 2e 20 49 66 20 y to newKey. If
3cd30 74 68 65 20 63 61 63 68 65 0a 2a 2a 20 70 72 65 the cache.** pre
3cd40 76 69 6f 75 73 6c 79 20 63 6f 6e 74 61 69 6e 73 viously contains
3cd50 20 61 6e 20 65 6e 74 72 79 20 61 73 73 6f 63 69 an entry associ
3cd60 61 74 65 64 20 77 69 74 68 20 6e 65 77 4b 65 79 ated with newKey
3cd70 2c 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a , it should be.*
3cd80 2a 20 64 69 73 63 61 72 64 65 64 2e 20 41 6e 79 * discarded. Any
3cd90 20 70 72 69 6f 72 20 63 61 63 68 65 20 65 6e 74 prior cache ent
3cda0 72 79 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ry associated wi
3cdb0 74 68 20 6e 65 77 4b 65 79 20 69 73 20 67 75 61 th newKey is gua
3cdc0 72 61 6e 74 65 65 64 20 6e 6f 74 0a 2a 2a 20 74 ranteed not.** t
3cdd0 6f 20 62 65 20 70 69 6e 6e 65 64 2e 0a 2a 2a 0a o be pinned..**.
3cde0 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 63 ** When SQLite c
3cdf0 61 6c 6c 73 20 74 68 65 20 78 54 72 75 6e 63 61 alls the xTrunca
3ce00 74 65 28 29 20 6d 65 74 68 6f 64 2c 20 74 68 65 te() method, the
3ce10 20 63 61 63 68 65 20 6d 75 73 74 20 64 69 73 63 cache must disc
3ce20 61 72 64 20 61 6c 6c 0a 2a 2a 20 65 78 69 73 74 ard all.** exist
3ce30 69 6e 67 20 63 61 63 68 65 20 65 6e 74 72 69 65 ing cache entrie
3ce40 73 20 77 69 74 68 20 70 61 67 65 20 6e 75 6d 62 s with page numb
3ce50 65 72 73 20 28 6b 65 79 73 29 20 67 72 65 61 74 ers (keys) great
3ce60 65 72 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c er than or equal
3ce70 0a 2a 2a 20 74 6f 20 74 68 65 20 76 61 6c 75 65 .** to the value
3ce80 20 6f 66 20 74 68 65 20 69 4c 69 6d 69 74 20 70 of the iLimit p
3ce90 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 arameter passed
3cea0 74 6f 20 78 54 72 75 6e 63 61 74 65 28 29 2e 20 to xTruncate().
3ceb0 49 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 If any.** of the
3cec0 73 65 20 70 61 67 65 73 20 61 72 65 20 70 69 6e se pages are pin
3ced0 6e 65 64 2c 20 74 68 65 79 20 61 72 65 20 69 6d ned, they are im
3cee0 70 6c 69 63 69 74 6c 79 20 75 6e 70 69 6e 6e 65 plicitly unpinne
3cef0 64 2c 20 6d 65 61 6e 69 6e 67 20 74 68 61 74 0a d, meaning that.
3cf00 2a 2a 20 74 68 65 79 20 63 61 6e 20 62 65 20 73 ** they can be s
3cf10 61 66 65 6c 79 20 64 69 73 63 61 72 64 65 64 2e afely discarded.
3cf20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 73 74 .**.** The xDest
3cf30 72 6f 79 28 29 20 6d 65 74 68 6f 64 20 69 73 20 roy() method is
3cf40 75 73 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 used to delete a
3cf50 20 63 61 63 68 65 20 61 6c 6c 6f 63 61 74 65 64 cache allocated
3cf60 20 62 79 20 78 43 72 65 61 74 65 28 29 2e 0a 2a by xCreate()..*
3cf70 2a 20 41 6c 6c 20 72 65 73 6f 75 72 63 65 73 20 * All resources
3cf80 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
3cf90 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63 61 the specified ca
3cfa0 63 68 65 20 73 68 6f 75 6c 64 20 62 65 20 66 72 che should be fr
3cfb0 65 65 64 2e 20 41 66 74 65 72 0a 2a 2a 20 63 61 eed. After.** ca
3cfc0 6c 6c 69 6e 67 20 74 68 65 20 78 44 65 73 74 72 lling the xDestr
3cfd0 6f 79 28 29 20 6d 65 74 68 6f 64 2c 20 53 51 4c oy() method, SQL
3cfe0 69 74 65 20 63 6f 6e 73 69 64 65 72 73 20 74 68 ite considers th
3cff0 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 e [sqlite3_pcach
3d000 65 2a 5d 0a 2a 2a 20 68 61 6e 64 6c 65 20 69 6e e*].** handle in
3d010 76 61 6c 69 64 2c 20 61 6e 64 20 77 69 6c 6c 20 valid, and will
3d020 6e 6f 74 20 75 73 65 20 69 74 20 77 69 74 68 20 not use it with
3d030 61 6e 79 20 6f 74 68 65 72 20 73 71 6c 69 74 65 any other sqlite
3d040 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 3_pcache_methods
3d050 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a .** functions..*
3d060 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
3d070 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f sqlite3_pcache_
3d080 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f methods sqlite3_
3d090 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 3b 0a pcache_methods;.
3d0a0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 70 struct sqlite3_p
3d0b0 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 20 7b 0a cache_methods {.
3d0c0 20 20 76 6f 69 64 20 2a 70 41 72 67 3b 0a 20 20 void *pArg;.
3d0d0 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 int (*xInit)(voi
3d0e0 64 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 d*);. void (*xS
3d0f0 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b hutdown)(void*);
3d100 0a 20 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 . sqlite3_pcach
3d110 65 20 2a 28 2a 78 43 72 65 61 74 65 29 28 69 6e e *(*xCreate)(in
3d120 74 20 73 7a 50 61 67 65 2c 20 69 6e 74 20 62 50 t szPage, int bP
3d130 75 72 67 65 61 62 6c 65 29 3b 0a 20 20 76 6f 69 urgeable);. voi
3d140 64 20 28 2a 78 43 61 63 68 65 73 69 7a 65 29 28 d (*xCachesize)(
3d150 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 2a 2c sqlite3_pcache*,
3d160 20 69 6e 74 20 6e 43 61 63 68 65 73 69 7a 65 29 int nCachesize)
3d170 3b 0a 20 20 69 6e 74 20 28 2a 78 50 61 67 65 63 ;. int (*xPagec
3d180 6f 75 6e 74 29 28 73 71 6c 69 74 65 33 5f 70 63 ount)(sqlite3_pc
3d190 61 63 68 65 2a 29 3b 0a 20 20 76 6f 69 64 20 2a ache*);. void *
3d1a0 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 (*xFetch)(sqlite
3d1b0 33 5f 70 63 61 63 68 65 2a 2c 20 75 6e 73 69 67 3_pcache*, unsig
3d1c0 6e 65 64 20 6b 65 79 2c 20 69 6e 74 20 63 72 65 ned key, int cre
3d1d0 61 74 65 46 6c 61 67 29 3b 0a 20 20 76 6f 69 64 ateFlag);. void
3d1e0 20 28 2a 78 55 6e 70 69 6e 29 28 73 71 6c 69 74 (*xUnpin)(sqlit
3d1f0 65 33 5f 70 63 61 63 68 65 2a 2c 20 76 6f 69 64 e3_pcache*, void
3d200 2a 2c 20 69 6e 74 20 64 69 73 63 61 72 64 29 3b *, int discard);
3d210 0a 20 20 76 6f 69 64 20 28 2a 78 52 65 6b 65 79 . void (*xRekey
3d220 29 28 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 )(sqlite3_pcache
3d230 2a 2c 20 76 6f 69 64 2a 2c 20 75 6e 73 69 67 6e *, void*, unsign
3d240 65 64 20 6f 6c 64 4b 65 79 2c 20 75 6e 73 69 67 ed oldKey, unsig
3d250 6e 65 64 20 6e 65 77 4b 65 79 29 3b 0a 20 20 76 ned newKey);. v
3d260 6f 69 64 20 28 2a 78 54 72 75 6e 63 61 74 65 29 oid (*xTruncate)
3d270 28 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 2a (sqlite3_pcache*
3d280 2c 20 75 6e 73 69 67 6e 65 64 20 69 4c 69 6d 69 , unsigned iLimi
3d290 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 65 t);. void (*xDe
3d2a0 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 70 stroy)(sqlite3_p
3d2b0 63 61 63 68 65 2a 29 3b 0a 7d 3b 0a 0a 2f 2a 0a cache*);.};../*.
3d2c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 6c ** CAPI3REF: Onl
3d2d0 69 6e 65 20 42 61 63 6b 75 70 20 4f 62 6a 65 63 ine Backup Objec
3d2e0 74 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 t.** EXPERIMENTA
3d2f0 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 L.**.** The sqli
3d300 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63 te3_backup objec
3d310 74 20 72 65 63 6f 72 64 73 20 73 74 61 74 65 20 t records state
3d320 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 information abou
3d330 74 20 61 6e 20 6f 6e 67 6f 69 6e 67 0a 2a 2a 20 t an ongoing.**
3d340 6f 6e 6c 69 6e 65 20 62 61 63 6b 75 70 20 6f 70 online backup op
3d350 65 72 61 74 69 6f 6e 2e 20 20 54 68 65 20 73 71 eration. The sq
3d360 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a lite3_backup obj
3d370 65 63 74 20 69 73 20 63 72 65 61 74 65 64 20 62 ect is created b
3d380 79 0a 2a 2a 20 61 20 63 61 6c 6c 20 74 6f 20 5b y.** a call to [
3d390 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 69 sqlite3_backup_i
3d3a0 6e 69 74 28 29 5d 20 61 6e 64 20 69 73 20 64 65 nit()] and is de
3d3b0 73 74 72 6f 79 65 64 20 62 79 20 61 20 63 61 6c stroyed by a cal
3d3c0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 l to.** [sqlite3
3d3d0 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 29 _backup_finish()
3d3e0 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 ]..**.** See Als
3d3f0 6f 3a 20 5b 55 73 69 6e 67 20 74 68 65 20 53 51 o: [Using the SQ
3d400 4c 69 74 65 20 4f 6e 6c 69 6e 65 20 42 61 63 6b Lite Online Back
3d410 75 70 20 41 50 49 5d 0a 2a 2f 0a 74 79 70 65 64 up API].*/.typed
3d420 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
3d430 33 5f 62 61 63 6b 75 70 20 73 71 6c 69 74 65 33 3_backup sqlite3
3d440 5f 62 61 63 6b 75 70 3b 0a 0a 2f 2a 0a 2a 2a 20 _backup;../*.**
3d450 43 41 50 49 33 52 45 46 3a 20 4f 6e 6c 69 6e 65 CAPI3REF: Online
3d460 20 42 61 63 6b 75 70 20 41 50 49 2e 0a 2a 2a 20 Backup API..**
3d470 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a EXPERIMENTAL.**.
3d480 2a 2a 20 54 68 69 73 20 41 50 49 20 69 73 20 75 ** This API is u
3d490 73 65 64 20 74 6f 20 6f 76 65 72 77 72 69 74 65 sed to overwrite
3d4a0 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 the contents of
3d4b0 20 6f 6e 65 20 64 61 74 61 62 61 73 65 20 77 69 one database wi
3d4c0 74 68 20 74 68 61 74 0a 2a 2a 20 6f 66 20 61 6e th that.** of an
3d4d0 6f 74 68 65 72 2e 20 49 74 20 69 73 20 75 73 65 other. It is use
3d4e0 66 75 6c 20 65 69 74 68 65 72 20 66 6f 72 20 63 ful either for c
3d4f0 72 65 61 74 69 6e 67 20 62 61 63 6b 75 70 73 20 reating backups
3d500 6f 66 20 64 61 74 61 62 61 73 65 73 20 6f 72 0a of databases or.
3d510 2a 2a 20 66 6f 72 20 63 6f 70 79 69 6e 67 20 69 ** for copying i
3d520 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 n-memory databas
3d530 65 73 20 74 6f 20 6f 72 20 66 72 6f 6d 20 70 65 es to or from pe
3d540 72 73 69 73 74 65 6e 74 20 66 69 6c 65 73 2e 20 rsistent files.
3d550 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 6f 3a .**.** See Also:
3d560 20 5b 55 73 69 6e 67 20 74 68 65 20 53 51 4c 69 [Using the SQLi
3d570 74 65 20 4f 6e 6c 69 6e 65 20 42 61 63 6b 75 70 te Online Backup
3d580 20 41 50 49 5d 0a 2a 2a 0a 2a 2a 20 45 78 63 6c API].**.** Excl
3d590 75 73 69 76 65 20 61 63 63 65 73 73 20 69 73 20 usive access is
3d5a0 72 65 71 75 69 72 65 64 20 74 6f 20 74 68 65 20 required to the
3d5b0 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 destination data
3d5c0 62 61 73 65 20 66 6f 72 20 74 68 65 20 0a 2a 2a base for the .**
3d5d0 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 duration of the
3d5e0 20 6f 70 65 72 61 74 69 6f 6e 2e 20 48 6f 77 65 operation. Howe
3d5f0 76 65 72 20 74 68 65 20 73 6f 75 72 63 65 20 64 ver the source d
3d600 61 74 61 62 61 73 65 20 69 73 20 6f 6e 6c 79 0a atabase is only.
3d610 2a 2a 20 72 65 61 64 2d 6c 6f 63 6b 65 64 20 77 ** read-locked w
3d620 68 69 6c 65 20 69 74 20 69 73 20 61 63 74 75 61 hile it is actua
3d630 6c 6c 79 20 62 65 69 6e 67 20 72 65 61 64 2c 20 lly being read,
3d640 69 74 20 69 73 20 6e 6f 74 20 6c 6f 63 6b 65 64 it is not locked
3d650 0a 2a 2a 20 63 6f 6e 74 69 6e 75 6f 75 73 6c 79 .** continuously
3d660 20 66 6f 72 20 74 68 65 20 65 6e 74 69 72 65 20 for the entire
3d670 6f 70 65 72 61 74 69 6f 6e 2e 20 54 68 75 73 2c operation. Thus,
3d680 20 74 68 65 20 62 61 63 6b 75 70 20 6d 61 79 20 the backup may
3d690 62 65 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 be.** performed
3d6a0 6f 6e 20 61 20 6c 69 76 65 20 64 61 74 61 62 61 on a live databa
3d6b0 73 65 20 77 69 74 68 6f 75 74 20 70 72 65 76 65 se without preve
3d6c0 6e 74 69 6e 67 20 6f 74 68 65 72 20 75 73 65 72 nting other user
3d6d0 73 20 66 72 6f 6d 0a 2a 2a 20 77 72 69 74 69 6e s from.** writin
3d6e0 67 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 g to the databas
3d6f0 65 20 66 6f 72 20 61 6e 20 65 78 74 65 6e 64 65 e for an extende
3d700 64 20 70 65 72 69 6f 64 20 6f 66 20 74 69 6d 65 d period of time
3d710 2e 0a 2a 2a 20 0a 2a 2a 20 54 6f 20 70 65 72 66 ..** .** To perf
3d720 6f 72 6d 20 61 20 62 61 63 6b 75 70 20 6f 70 65 orm a backup ope
3d730 72 61 74 69 6f 6e 3a 20 0a 2a 2a 20 20 20 3c 6f ration: .** <o
3d740 6c 3e 0a 2a 2a 20 20 20 20 20 3c 6c 69 3e 3c 62 l>.** <li><b
3d750 3e 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f >sqlite3_backup_
3d760 69 6e 69 74 28 29 3c 2f 62 3e 20 69 73 20 63 61 init()</b> is ca
3d770 6c 6c 65 64 20 6f 6e 63 65 20 74 6f 20 69 6e 69 lled once to ini
3d780 74 69 61 6c 69 7a 65 20 74 68 65 0a 2a 2a 20 20 tialize the.**
3d790 20 20 20 20 20 20 20 62 61 63 6b 75 70 2c 20 0a backup, .
3d7a0 2a 2a 20 20 20 20 20 3c 6c 69 3e 3c 62 3e 73 71 ** <li><b>sq
3d7b0 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 lite3_backup_ste
3d7c0 70 28 29 3c 2f 62 3e 20 69 73 20 63 61 6c 6c 65 p()</b> is calle
3d7d0 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 d one or more ti
3d7e0 6d 65 73 20 74 6f 20 74 72 61 6e 73 66 65 72 20 mes to transfer
3d7f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 74 68 65 20 .** the
3d800 64 61 74 61 20 62 65 74 77 65 65 6e 20 74 68 65 data between the
3d810 20 74 77 6f 20 64 61 74 61 62 61 73 65 73 2c 20 two databases,
3d820 61 6e 64 20 66 69 6e 61 6c 6c 79 0a 2a 2a 20 20 and finally.**
3d830 20 20 20 3c 6c 69 3e 3c 62 3e 73 71 6c 69 74 65 <li><b>sqlite
3d840 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 3_backup_finish(
3d850 29 3c 2f 62 3e 20 69 73 20 63 61 6c 6c 65 64 20 )</b> is called
3d860 74 6f 20 72 65 6c 65 61 73 65 20 61 6c 6c 20 72 to release all r
3d870 65 73 6f 75 72 63 65 73 20 0a 2a 2a 20 20 20 20 esources .**
3d880 20 20 20 20 20 61 73 73 6f 63 69 61 74 65 64 20 associated
3d890 77 69 74 68 20 74 68 65 20 62 61 63 6b 75 70 20 with the backup
3d8a0 6f 70 65 72 61 74 69 6f 6e 2e 20 0a 2a 2a 20 20 operation. .**
3d8b0 20 3c 2f 6f 6c 3e 0a 2a 2a 20 54 68 65 72 65 20 </ol>.** There
3d8c0 73 68 6f 75 6c 64 20 62 65 20 65 78 61 63 74 6c should be exactl
3d8d0 79 20 6f 6e 65 20 63 61 6c 6c 20 74 6f 20 73 71 y one call to sq
3d8e0 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e lite3_backup_fin
3d8f0 69 73 68 28 29 20 66 6f 72 20 65 61 63 68 0a 2a ish() for each.*
3d900 2a 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c * successful cal
3d910 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 l to sqlite3_bac
3d920 6b 75 70 5f 69 6e 69 74 28 29 2e 0a 2a 2a 0a 2a kup_init()..**.*
3d930 2a 20 3c 62 3e 73 71 6c 69 74 65 33 5f 62 61 63 * <b>sqlite3_bac
3d940 6b 75 70 5f 69 6e 69 74 28 29 3c 2f 62 3e 0a 2a kup_init()</b>.*
3d950 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 74 *.** The first t
3d960 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 70 61 73 wo arguments pas
3d970 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f sed to [sqlite3_
3d980 62 61 63 6b 75 70 5f 69 6e 69 74 28 29 5d 20 61 backup_init()] a
3d990 72 65 20 74 68 65 20 64 61 74 61 62 61 73 65 0a re the database.
3d9a0 2a 2a 20 68 61 6e 64 6c 65 20 61 73 73 6f 63 69 ** handle associ
3d9b0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64 65 ated with the de
3d9c0 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 stination databa
3d9d0 73 65 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 se and the datab
3d9e0 61 73 65 20 6e 61 6d 65 20 0a 2a 2a 20 75 73 65 ase name .** use
3d9f0 64 20 74 6f 20 61 74 74 61 63 68 20 74 68 65 20 d to attach the
3da00 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 destination data
3da10 62 61 73 65 20 74 6f 20 74 68 65 20 68 61 6e 64 base to the hand
3da20 6c 65 2e 20 54 68 65 20 64 61 74 61 62 61 73 65 le. The database
3da30 20 6e 61 6d 65 0a 2a 2a 20 69 73 20 22 6d 61 69 name.** is "mai
3da40 6e 22 20 66 6f 72 20 74 68 65 20 6d 61 69 6e 20 n" for the main
3da50 64 61 74 61 62 61 73 65 2c 20 22 74 65 6d 70 22 database, "temp"
3da60 20 66 6f 72 20 74 68 65 20 74 65 6d 70 6f 72 61 for the tempora
3da70 72 79 20 64 61 74 61 62 61 73 65 2c 20 6f 72 0a ry database, or.
3da80 2a 2a 20 74 68 65 20 6e 61 6d 65 20 73 70 65 63 ** the name spec
3da90 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 ified as part of
3daa0 20 74 68 65 20 5b 41 54 54 41 43 48 5d 20 73 74 the [ATTACH] st
3dab0 61 74 65 6d 65 6e 74 20 69 66 20 74 68 65 20 64 atement if the d
3dac0 65 73 74 69 6e 61 74 69 6f 6e 20 69 73 0a 2a 2a estination is.**
3dad0 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 74 an attached dat
3dae0 61 62 61 73 65 2e 20 54 68 65 20 74 68 69 72 64 abase. The third
3daf0 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 and fourth argu
3db00 6d 65 6e 74 73 20 70 61 73 73 65 64 20 74 6f 20 ments passed to
3db10 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 6b .** sqlite3_back
3db20 75 70 5f 69 6e 69 74 28 29 20 69 64 65 6e 74 69 up_init() identi
3db30 66 79 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 fy the [database
3db40 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 connection].**
3db50 61 6e 64 20 64 61 74 61 62 61 73 65 20 6e 61 6d and database nam
3db60 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 61 63 63 e used.** to acc
3db70 65 73 73 20 74 68 65 20 73 6f 75 72 63 65 20 64 ess the source d
3db80 61 74 61 62 61 73 65 2e 20 54 68 65 20 76 61 6c atabase. The val
3db90 75 65 73 20 70 61 73 73 65 64 20 66 6f 72 20 74 ues passed for t
3dba0 68 65 20 73 6f 75 72 63 65 20 61 6e 64 20 0a 2a he source and .*
3dbb0 2a 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 5b 64 * destination [d
3dbc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
3dbd0 6f 6e 5d 20 70 61 72 61 6d 65 74 65 72 73 20 6d on] parameters m
3dbe0 75 73 74 20 6e 6f 74 20 62 65 20 74 68 65 20 73 ust not be the s
3dbf0 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e ame..**.** If an
3dc00 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 69 error occurs wi
3dc10 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 62 61 63 thin sqlite3_bac
3dc20 6b 75 70 5f 69 6e 69 74 28 29 2c 20 74 68 65 6e kup_init(), then
3dc30 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 NULL is returne
3dc40 64 0a 2a 2a 20 61 6e 64 20 61 6e 20 65 72 72 6f d.** and an erro
3dc50 72 20 63 6f 64 65 20 61 6e 64 20 65 72 72 6f 72 r code and error
3dc60 20 6d 65 73 73 61 67 65 20 77 72 69 74 74 65 6e message written
3dc70 20 69 6e 74 6f 20 74 68 65 20 5b 64 61 74 61 62 into the [datab
3dc80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
3dc90 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 .** passed as th
3dca0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
3dcb0 2e 20 54 68 65 79 20 6d 61 79 20 62 65 20 72 65 . They may be re
3dcc0 74 72 69 65 76 65 64 20 75 73 69 6e 67 20 74 68 trieved using th
3dcd0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 e.** [sqlite3_er
3dce0 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 rcode()], [sqlit
3dcf0 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e e3_errmsg()], an
3dd00 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 d [sqlite3_errms
3dd10 67 31 36 28 29 5d 20 66 75 6e 63 74 69 6f 6e 73 g16()] functions
3dd20 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 ..** Otherwise,
3dd30 69 66 20 73 75 63 63 65 73 73 66 75 6c 2c 20 61 if successful, a
3dd40 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b pointer to an [
3dd50 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 sqlite3_backup]
3dd60 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 72 65 74 object is.** ret
3dd70 75 72 6e 65 64 2e 20 54 68 69 73 20 70 6f 69 6e urned. This poin
3dd80 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 ter may be used
3dd90 77 69 74 68 20 74 68 65 20 73 71 6c 69 74 65 33 with the sqlite3
3dda0 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 61 _backup_step() a
3ddb0 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 nd.** sqlite3_ba
3ddc0 63 6b 75 70 5f 66 69 6e 69 73 68 28 29 20 66 75 ckup_finish() fu
3ddd0 6e 63 74 69 6f 6e 73 20 74 6f 20 70 65 72 66 6f nctions to perfo
3dde0 72 6d 20 74 68 65 20 73 70 65 63 69 66 69 65 64 rm the specified
3ddf0 20 62 61 63 6b 75 70 20 0a 2a 2a 20 6f 70 65 72 backup .** oper
3de00 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e ation..**.** <b>
3de10 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 sqlite3_backup_s
3de20 74 65 70 28 29 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 tep()</b>.**.**
3de30 46 75 6e 63 74 69 6f 6e 20 5b 73 71 6c 69 74 65 Function [sqlite
3de40 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 5d 3_backup_step()]
3de50 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 70 79 is used to copy
3de60 20 75 70 20 74 6f 20 6e 50 61 67 65 20 70 61 67 up to nPage pag
3de70 65 73 20 62 65 74 77 65 65 6e 20 0a 2a 2a 20 74 es between .** t
3de80 68 65 20 73 6f 75 72 63 65 20 61 6e 64 20 64 65 he source and de
3de90 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 stination databa
3dea0 73 65 73 2c 20 77 68 65 72 65 20 6e 50 61 67 65 ses, where nPage
3deb0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 is the value of
3dec0 20 74 68 65 20 0a 2a 2a 20 73 65 63 6f 6e 64 20 the .** second
3ded0 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 parameter passed
3dee0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b to sqlite3_back
3def0 75 70 5f 73 74 65 70 28 29 2e 20 49 66 20 6e 50 up_step(). If nP
3df00 61 67 65 20 69 73 20 61 20 6e 65 67 61 74 69 76 age is a negativ
3df10 65 0a 2a 2a 20 76 61 6c 75 65 2c 20 61 6c 6c 20 e.** value, all
3df20 72 65 6d 61 69 6e 69 6e 67 20 73 6f 75 72 63 65 remaining source
3df30 20 70 61 67 65 73 20 61 72 65 20 63 6f 70 69 65 pages are copie
3df40 64 2e 20 49 66 20 74 68 65 20 72 65 71 75 69 72 d. If the requir
3df50 65 64 20 70 61 67 65 73 20 61 72 65 20 0a 2a 2a ed pages are .**
3df60 20 73 75 63 63 65 73 66 75 6c 6c 79 20 63 6f 70 succesfully cop
3df70 69 65 64 2c 20 62 75 74 20 74 68 65 72 65 20 61 ied, but there a
3df80 72 65 20 73 74 69 6c 6c 20 6d 6f 72 65 20 70 61 re still more pa
3df90 67 65 73 20 74 6f 20 63 6f 70 79 20 62 65 66 6f ges to copy befo
3dfa0 72 65 20 74 68 65 20 0a 2a 2a 20 62 61 63 6b 75 re the .** backu
3dfb0 70 20 69 73 20 63 6f 6d 70 6c 65 74 65 2c 20 69 p is complete, i
3dfc0 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 t returns [SQLIT
3dfd0 45 5f 4f 4b 5d 2e 20 49 66 20 6e 6f 20 65 72 72 E_OK]. If no err
3dfe0 6f 72 20 6f 63 63 75 72 65 64 20 61 6e 64 20 74 or occured and t
3dff0 68 65 72 65 20 0a 2a 2a 20 61 72 65 20 6e 6f 20 here .** are no
3e000 6d 6f 72 65 20 70 61 67 65 73 20 74 6f 20 63 6f more pages to co
3e010 70 79 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 py, then [SQLITE
3e020 5f 44 4f 4e 45 5d 20 69 73 20 72 65 74 75 72 6e _DONE] is return
3e030 65 64 2e 20 49 66 20 61 6e 20 65 72 72 6f 72 20 ed. If an error
3e040 0a 2a 2a 20 6f 63 63 75 72 73 2c 20 74 68 65 6e .** occurs, then
3e050 20 61 6e 20 53 51 4c 69 74 65 20 65 72 72 6f 72 an SQLite error
3e060 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 code is returne
3e070 64 2e 20 41 73 20 77 65 6c 6c 20 61 73 20 5b 53 d. As well as [S
3e080 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e 64 0a 2a 2a QLITE_OK] and.**
3e090 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 [SQLITE_DONE],
3e0a0 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 a call to sqlite
3e0b0 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 3_backup_step()
3e0c0 6d 61 79 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 may return [SQLI
3e0d0 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2c 0a 2a 2a TE_READONLY],.**
3e0e0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c [SQLITE_NOMEM],
3e0f0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 [SQLITE_BUSY],
3e100 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5d 2c [SQLITE_LOCKED],
3e110 20 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 or an.** [SQLIT
3e120 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 7c E_IOERR_ACCESS |
3e130 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 58 58 SQLITE_IOERR_XX
3e140 58 5d 20 65 78 74 65 6e 64 65 64 20 65 72 72 6f X] extended erro
3e150 72 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 41 73 r code..**.** As
3e160 20 77 65 6c 6c 20 61 73 20 74 68 65 20 63 61 73 well as the cas
3e170 65 20 77 68 65 72 65 20 74 68 65 20 64 65 73 74 e where the dest
3e180 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 73 65 ination database
3e190 20 66 69 6c 65 20 77 61 73 20 6f 70 65 6e 65 64 file was opened
3e1a0 20 66 6f 72 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c for.** read-onl
3e1b0 79 20 61 63 63 65 73 73 2c 20 73 71 6c 69 74 65 y access, sqlite
3e1c0 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 3_backup_step()
3e1d0 6d 61 79 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 may return [SQLI
3e1e0 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 20 69 66 0a TE_READONLY] if.
3e1f0 2a 2a 20 74 68 65 20 64 65 73 74 69 6e 61 74 69 ** the destinati
3e200 6f 6e 20 69 73 20 61 6e 20 69 6e 2d 6d 65 6d 6f on is an in-memo
3e210 72 79 20 64 61 74 61 62 61 73 65 20 77 69 74 68 ry database with
3e220 20 61 20 64 69 66 66 65 72 65 6e 74 20 70 61 67 a different pag
3e230 65 20 73 69 7a 65 0a 2a 2a 20 66 72 6f 6d 20 74 e size.** from t
3e240 68 65 20 73 6f 75 72 63 65 20 64 61 74 61 62 61 he source databa
3e250 73 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c se..**.** If sql
3e260 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 ite3_backup_step
3e270 28 29 20 63 61 6e 6e 6f 74 20 6f 62 74 61 69 6e () cannot obtain
3e280 20 61 20 72 65 71 75 69 72 65 64 20 66 69 6c 65 a required file
3e290 2d 73 79 73 74 65 6d 20 6c 6f 63 6b 2c 20 74 68 -system lock, th
3e2a0 65 6e 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 en.** the [sqlit
3e2b0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 e3_busy_handler
3e2c0 7c 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 66 | busy-handler f
3e2d0 75 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 69 73 20 69 unction].** is i
3e2e0 6e 76 6f 6b 65 64 20 28 69 66 20 6f 6e 65 20 69 nvoked (if one i
3e2f0 73 20 73 70 65 63 69 66 69 65 64 29 2e 20 49 66 s specified). If
3e300 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 2d 68 61 the .** busy-ha
3e310 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 6e 6f ndler returns no
3e320 6e 2d 7a 65 72 6f 20 62 65 66 6f 72 65 20 74 68 n-zero before th
3e330 65 20 6c 6f 63 6b 20 69 73 20 61 76 61 69 6c 61 e lock is availa
3e340 62 6c 65 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 53 ble, then .** [S
3e350 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20 72 QLITE_BUSY] is r
3e360 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 eturned to the c
3e370 61 6c 6c 65 72 2e 20 49 6e 20 74 68 69 73 20 63 aller. In this c
3e380 61 73 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a ase the call to.
3e390 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 ** sqlite3_backu
3e3a0 70 5f 73 74 65 70 28 29 20 63 61 6e 20 62 65 20 p_step() can be
3e3b0 72 65 74 72 69 65 64 20 6c 61 74 65 72 2e 20 49 retried later. I
3e3c0 66 20 74 68 65 20 73 6f 75 72 63 65 0a 2a 2a 20 f the source.**
3e3d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
3e3e0 74 69 6f 6e 5d 0a 2a 2a 20 69 73 20 62 65 69 6e tion].** is bein
3e3f0 67 20 75 73 65 64 20 74 6f 20 77 72 69 74 65 20 g used to write
3e400 74 6f 20 74 68 65 20 73 6f 75 72 63 65 20 64 61 to the source da
3e410 74 61 62 61 73 65 20 77 68 65 6e 20 73 71 6c 69 tabase when sqli
3e420 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 te3_backup_step(
3e430 29 0a 2a 2a 20 69 73 20 63 61 6c 6c 65 64 2c 20 ).** is called,
3e440 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 then [SQLITE_LOC
3e450 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 KED] is returned
3e460 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 20 41 67 immediately. Ag
3e470 61 69 6e 2c 20 69 6e 20 74 68 69 73 0a 2a 2a 20 ain, in this.**
3e480 63 61 73 65 20 74 68 65 20 63 61 6c 6c 20 74 6f case the call to
3e490 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f sqlite3_backup_
3e4a0 73 74 65 70 28 29 20 63 61 6e 20 62 65 20 72 65 step() can be re
3e4b0 74 72 69 65 64 20 6c 61 74 65 72 20 6f 6e 2e 20 tried later on.
3e4c0 49 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f If.** [SQLITE_IO
3e4d0 45 52 52 5f 41 43 43 45 53 53 20 7c 20 53 51 4c ERR_ACCESS | SQL
3e4e0 49 54 45 5f 49 4f 45 52 52 5f 58 58 58 5d 2c 20 ITE_IOERR_XXX],
3e4f0 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 [SQLITE_NOMEM],
3e500 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 45 or.** [SQLITE_RE
3e510 41 44 4f 4e 4c 59 5d 20 69 73 20 72 65 74 75 72 ADONLY] is retur
3e520 6e 65 64 2c 20 74 68 65 6e 20 0a 2a 2a 20 74 68 ned, then .** th
3e530 65 72 65 20 69 73 20 6e 6f 20 70 6f 69 6e 74 20 ere is no point
3e540 69 6e 20 72 65 74 72 79 69 6e 67 20 74 68 65 20 in retrying the
3e550 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
3e560 62 61 63 6b 75 70 5f 73 74 65 70 28 29 2e 20 54 backup_step(). T
3e570 68 65 73 65 20 0a 2a 2a 20 65 72 72 6f 72 73 20 hese .** errors
3e580 61 72 65 20 63 6f 6e 73 69 64 65 72 65 64 20 66 are considered f
3e590 61 74 61 6c 2e 20 41 74 20 74 68 69 73 20 70 6f atal. At this po
3e5a0 69 6e 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 int the applicat
3e5b0 69 6f 6e 20 6d 75 73 74 20 61 63 63 65 70 74 20 ion must accept
3e5c0 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 62 61 63 .** that the bac
3e5d0 6b 75 70 20 6f 70 65 72 61 74 69 6f 6e 20 68 61 kup operation ha
3e5e0 73 20 66 61 69 6c 65 64 20 61 6e 64 20 70 61 73 s failed and pas
3e5f0 73 20 74 68 65 20 62 61 63 6b 75 70 20 6f 70 65 s the backup ope
3e600 72 61 74 69 6f 6e 20 68 61 6e 64 6c 65 20 0a 2a ration handle .*
3e610 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 * to the sqlite3
3e620 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 29 _backup_finish()
3e630 20 74 6f 20 72 65 6c 65 61 73 65 20 61 73 73 6f to release asso
3e640 63 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 ciated resources
3e650 2e 0a 2a 2a 0a 2a 2a 20 46 6f 6c 6c 6f 77 69 6e ..**.** Followin
3e660 67 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c g the first call
3e670 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 61 63 6b to sqlite3_back
3e680 75 70 5f 73 74 65 70 28 29 2c 20 61 6e 20 65 78 up_step(), an ex
3e690 63 6c 75 73 69 76 65 20 6c 6f 63 6b 20 69 73 0a clusive lock is.
3e6a0 2a 2a 20 6f 62 74 61 69 6e 65 64 20 6f 6e 20 74 ** obtained on t
3e6b0 68 65 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 66 he destination f
3e6c0 69 6c 65 2e 20 49 74 20 69 73 20 6e 6f 74 20 72 ile. It is not r
3e6d0 65 6c 65 61 73 65 64 20 75 6e 74 69 6c 20 65 69 eleased until ei
3e6e0 74 68 65 72 20 0a 2a 2a 20 73 71 6c 69 74 65 33 ther .** sqlite3
3e6f0 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 29 _backup_finish()
3e700 20 69 73 20 63 61 6c 6c 65 64 20 6f 72 20 74 68 is called or th
3e710 65 20 62 61 63 6b 75 70 20 6f 70 65 72 61 74 69 e backup operati
3e720 6f 6e 20 69 73 20 63 6f 6d 70 6c 65 74 65 20 0a on is complete .
3e730 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 62 ** and sqlite3_b
3e740 61 63 6b 75 70 5f 73 74 65 70 28 29 20 72 65 74 ackup_step() ret
3e750 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 4f 4e urns [SQLITE_DON
3e760 45 5d 2e 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 E]. Additionally
3e770 2c 20 65 61 63 68 20 74 69 6d 65 20 0a 2a 2a 20 , each time .**
3e780 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 a call to sqlite
3e790 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 3_backup_step()
3e7a0 69 73 20 6d 61 64 65 20 61 20 5b 73 68 61 72 65 is made a [share
3e7b0 64 20 6c 6f 63 6b 5d 20 69 73 20 6f 62 74 61 69 d lock] is obtai
3e7c0 6e 65 64 20 6f 6e 0a 2a 2a 20 74 68 65 20 73 6f ned on.** the so
3e7d0 75 72 63 65 20 64 61 74 61 62 61 73 65 20 66 69 urce database fi
3e7e0 6c 65 2e 20 54 68 69 73 20 6c 6f 63 6b 20 69 73 le. This lock is
3e7f0 20 72 65 6c 65 61 73 65 64 20 62 65 66 6f 72 65 released before
3e800 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f the.** sqlite3_
3e810 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 63 61 backup_step() ca
3e820 6c 6c 20 72 65 74 75 72 6e 73 2e 20 42 65 63 61 ll returns. Beca
3e830 75 73 65 20 74 68 65 20 73 6f 75 72 63 65 20 64 use the source d
3e840 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a atabase is not.*
3e850 2a 20 6c 6f 63 6b 65 64 20 62 65 74 77 65 65 6e * locked between
3e860 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 calls to sqlite
3e870 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 2c 3_backup_step(),
3e880 20 69 74 20 6d 61 79 20 62 65 20 6d 6f 64 69 66 it may be modif
3e890 69 65 64 20 6d 69 64 2d 77 61 79 0a 2a 2a 20 74 ied mid-way.** t
3e8a0 68 72 6f 75 67 68 20 74 68 65 20 62 61 63 6b 75 hrough the backu
3e8b0 70 20 70 72 6f 63 65 64 75 72 65 2e 20 49 66 20 p procedure. If
3e8c0 74 68 65 20 73 6f 75 72 63 65 20 64 61 74 61 62 the source datab
3e8d0 61 73 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 ase is modified
3e8e0 62 79 20 61 6e 0a 2a 2a 20 65 78 74 65 72 6e 61 by an.** externa
3e8f0 6c 20 70 72 6f 63 65 73 73 20 6f 72 20 76 69 61 l process or via
3e900 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a database conn
3e910 65 63 74 69 6f 6e 20 6f 74 68 65 72 20 74 68 61 ection other tha
3e920 6e 20 74 68 65 20 6f 6e 65 20 62 65 69 6e 67 0a n the one being.
3e930 2a 2a 20 75 73 65 64 20 62 79 20 74 68 65 20 62 ** used by the b
3e940 61 63 6b 75 70 20 6f 70 65 72 61 74 69 6f 6e 2c ackup operation,
3e950 20 74 68 65 6e 20 74 68 65 20 62 61 63 6b 75 70 then the backup
3e960 20 77 69 6c 6c 20 62 65 20 74 72 61 6e 73 70 61 will be transpa
3e970 72 65 6e 74 6c 79 0a 2a 2a 20 72 65 73 74 61 72 rently.** restar
3e980 74 65 64 20 62 79 20 74 68 65 20 6e 65 78 74 20 ted by the next
3e990 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
3e9a0 62 61 63 6b 75 70 5f 73 74 65 70 28 29 2e 20 49 backup_step(). I
3e9b0 66 20 74 68 65 20 73 6f 75 72 63 65 20 0a 2a 2a f the source .**
3e9c0 20 64 61 74 61 62 61 73 65 20 69 73 20 6d 6f 64 database is mod
3e9d0 69 66 69 65 64 20 62 79 20 74 68 65 20 75 73 69 ified by the usi
3e9e0 6e 67 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 ng the same data
3e9f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
3ea00 61 73 20 69 73 20 75 73 65 64 0a 2a 2a 20 62 79 as is used.** by
3ea10 20 74 68 65 20 62 61 63 6b 75 70 20 6f 70 65 72 the backup oper
3ea20 61 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 ation, then the
3ea30 62 61 63 6b 75 70 20 64 61 74 61 62 61 73 65 20 backup database
3ea40 69 73 20 74 72 61 6e 73 70 61 72 65 6e 74 6c 79 is transparently
3ea50 20 0a 2a 2a 20 75 70 64 61 74 65 64 20 61 74 20 .** updated at
3ea60 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a the same time..*
3ea70 2a 0a 2a 2a 20 3c 62 3e 73 71 6c 69 74 65 33 5f *.** <b>sqlite3_
3ea80 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 29 3c backup_finish()<
3ea90 2f 62 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 63 65 20 73 /b>.**.** Once s
3eaa0 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 qlite3_backup_st
3eab0 65 70 28 29 20 68 61 73 20 72 65 74 75 72 6e 65 ep() has returne
3eac0 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c d [SQLITE_DONE],
3ead0 20 6f 72 20 77 68 65 6e 20 74 68 65 20 0a 2a 2a or when the .**
3eae0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 69 73 application wis
3eaf0 68 65 73 20 74 6f 20 61 62 61 6e 64 6f 6e 20 74 hes to abandon t
3eb00 68 65 20 62 61 63 6b 75 70 20 6f 70 65 72 61 74 he backup operat
3eb10 69 6f 6e 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 ion, the [sqlite
3eb20 33 5f 62 61 63 6b 75 70 5d 0a 2a 2a 20 6f 62 6a 3_backup].** obj
3eb30 65 63 74 20 73 68 6f 75 6c 64 20 62 65 20 70 61 ect should be pa
3eb40 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f ssed to sqlite3_
3eb50 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 29 2e backup_finish().
3eb60 20 54 68 69 73 20 72 65 6c 65 61 73 65 73 20 61 This releases a
3eb70 6c 6c 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 ll.** resources
3eb80 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
3eb90 74 68 65 20 62 61 63 6b 75 70 20 6f 70 65 72 61 the backup opera
3eba0 74 69 6f 6e 2e 20 49 66 20 73 71 6c 69 74 65 33 tion. If sqlite3
3ebb0 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 0a 2a _backup_step().*
3ebc0 2a 20 68 61 73 20 6e 6f 74 20 79 65 74 20 72 65 * has not yet re
3ebd0 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 turned [SQLITE_D
3ebe0 4f 4e 45 5d 2c 20 74 68 65 6e 20 61 6e 79 20 61 ONE], then any a
3ebf0 63 74 69 76 65 20 77 72 69 74 65 2d 74 72 61 6e ctive write-tran
3ec00 73 61 63 74 69 6f 6e 20 6f 6e 20 74 68 65 0a 2a saction on the.*
3ec10 2a 20 64 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 * destination da
3ec20 74 61 62 61 73 65 20 69 73 20 72 6f 6c 6c 65 64 tabase is rolled
3ec30 20 62 61 63 6b 2e 20 54 68 65 20 5b 73 71 6c 69 back. The [sqli
3ec40 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 te3_backup] obje
3ec50 63 74 20 69 73 20 69 6e 76 61 6c 69 64 0a 2a 2a ct is invalid.**
3ec60 20 61 6e 64 20 6d 61 79 20 6e 6f 74 20 62 65 20 and may not be
3ec70 75 73 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 used following a
3ec80 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
3ec90 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 29 _backup_finish()
3eca0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 ..**.** The valu
3ecb0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 e returned by sq
3ecc0 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e lite3_backup_fin
3ecd0 69 73 68 20 69 73 20 5b 53 51 4c 49 54 45 5f 4f ish is [SQLITE_O
3ece0 4b 5d 20 69 66 20 6e 6f 20 65 72 72 6f 72 0a 2a K] if no error.*
3ecf0 2a 20 6f 63 63 75 72 72 65 64 2c 20 72 65 67 61 * occurred, rega
3ed00 72 64 6c 65 73 73 20 6f 72 20 77 68 65 74 68 65 rdless or whethe
3ed10 72 20 6f 72 20 6e 6f 74 20 73 71 6c 69 74 65 33 r or not sqlite3
3ed20 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 77 _backup_step() w
3ed30 61 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 61 20 73 as called.** a s
3ed40 75 66 66 69 63 69 65 6e 74 20 6e 75 6d 62 65 72 ufficient number
3ed50 20 6f 66 20 74 69 6d 65 73 20 74 6f 20 63 6f 6d of times to com
3ed60 70 6c 65 74 65 20 74 68 65 20 62 61 63 6b 75 70 plete the backup
3ed70 20 6f 70 65 72 61 74 69 6f 6e 2e 20 4f 72 2c 20 operation. Or,
3ed80 69 66 0a 2a 2a 20 61 6e 20 6f 75 74 2d 6f 66 2d if.** an out-of-
3ed90 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e memory condition
3eda0 20 6f 72 20 49 4f 20 65 72 72 6f 72 20 6f 63 63 or IO error occ
3edb0 75 72 65 64 20 64 75 72 69 6e 67 20 61 20 63 61 ured during a ca
3edc0 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 ll to.** sqlite3
3edd0 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 20 74 _backup_step() t
3ede0 68 65 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 hen [SQLITE_NOME
3edf0 4d 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c M] or an.** [SQL
3ee00 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 ITE_IOERR_ACCESS
3ee10 20 7c 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f | SQLITE_IOERR_
3ee20 58 58 58 5d 20 65 72 72 6f 72 20 63 6f 64 65 0a XXX] error code.
3ee30 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 ** is returned.
3ee40 49 6e 20 74 68 69 73 20 63 61 73 65 20 74 68 65 In this case the
3ee50 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 error code and
3ee60 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 an error message
3ee70 20 61 72 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 are.** written
3ee80 74 6f 20 74 68 65 20 64 65 73 74 69 6e 61 74 69 to the destinati
3ee90 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e on [database con
3eea0 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 nection]..**.**
3eeb0 41 20 72 65 74 75 72 6e 20 6f 66 20 5b 53 51 4c A return of [SQL
3eec0 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 ITE_BUSY] or [SQ
3eed0 4c 49 54 45 5f 4c 4f 43 4b 45 44 5d 20 66 72 6f LITE_LOCKED] fro
3eee0 6d 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 m sqlite3_backup
3eef0 5f 73 74 65 70 28 29 20 69 73 0a 2a 2a 20 6e 6f _step() is.** no
3ef00 74 20 61 20 70 65 72 6d 61 6e 65 6e 74 20 65 72 t a permanent er
3ef10 72 6f 72 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 ror and does not
3ef20 20 61 66 66 65 63 74 20 74 68 65 20 72 65 74 75 affect the retu
3ef30 72 6e 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 73 rn value of.** s
3ef40 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 qlite3_backup_fi
3ef50 6e 69 73 68 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 nish()..**.** <b
3ef60 3e 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f >sqlite3_backup_
3ef70 72 65 6d 61 69 6e 69 6e 67 28 29 2c 20 73 71 6c remaining(), sql
3ef80 69 74 65 33 5f 62 61 63 6b 75 70 5f 70 61 67 65 ite3_backup_page
3ef90 63 6f 75 6e 74 28 29 3c 2f 62 3e 0a 2a 2a 0a 2a count()</b>.**.*
3efa0 2a 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 * Each call to s
3efb0 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 qlite3_backup_st
3efc0 65 70 28 29 20 73 65 74 73 20 74 77 6f 20 76 61 ep() sets two va
3efd0 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 74 65 lues stored inte
3efe0 72 6e 61 6c 6c 79 0a 2a 2a 20 62 79 20 61 6e 20 rnally.** by an
3eff0 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d [sqlite3_backup]
3f000 20 6f 62 6a 65 63 74 2e 20 54 68 65 20 6e 75 6d object. The num
3f010 62 65 72 20 6f 66 20 70 61 67 65 73 20 73 74 69 ber of pages sti
3f020 6c 6c 20 74 6f 20 62 65 20 62 61 63 6b 65 64 0a ll to be backed.
3f030 2a 2a 20 75 70 2c 20 77 68 69 63 68 20 6d 61 79 ** up, which may
3f040 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20 73 be queried by s
3f050 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 72 65 qlite3_backup_re
3f060 6d 61 69 6e 69 6e 67 28 29 2c 20 61 6e 64 20 74 maining(), and t
3f070 68 65 20 74 6f 74 61 6c 0a 2a 2a 20 6e 75 6d 62 he total.** numb
3f080 65 72 20 6f 66 20 70 61 67 65 73 20 69 6e 20 74 er of pages in t
3f090 68 65 20 73 6f 75 72 63 65 20 64 61 74 61 62 61 he source databa
3f0a0 73 65 20 66 69 6c 65 2c 20 77 68 69 63 68 20 6d se file, which m
3f0b0 61 79 20 62 65 20 71 75 65 72 69 65 64 20 62 79 ay be queried by
3f0c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 6b .** sqlite3_back
3f0d0 75 70 5f 70 61 67 65 63 6f 75 6e 74 28 29 2e 0a up_pagecount()..
3f0e0 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 73 **.** The values
3f0f0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 returned by the
3f100 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 se functions are
3f110 20 6f 6e 6c 79 20 75 70 64 61 74 65 64 20 62 79 only updated by
3f120 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 61 63 6b .** sqlite3_back
3f130 75 70 5f 73 74 65 70 28 29 2e 20 49 66 20 74 68 up_step(). If th
3f140 65 20 73 6f 75 72 63 65 20 64 61 74 61 62 61 73 e source databas
3f150 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64 75 e is modified du
3f160 72 69 6e 67 20 61 20 62 61 63 6b 75 70 0a 2a 2a ring a backup.**
3f170 20 6f 70 65 72 61 74 69 6f 6e 2c 20 74 68 65 6e operation, then
3f180 20 74 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 the values are
3f190 6e 6f 74 20 75 70 64 61 74 65 64 20 74 6f 20 61 not updated to a
3f1a0 63 63 6f 75 6e 74 20 66 6f 72 20 61 6e 79 20 65 ccount for any e
3f1b0 78 74 72 61 0a 2a 2a 20 70 61 67 65 73 20 74 68 xtra.** pages th
3f1c0 61 74 20 6e 65 65 64 20 74 6f 20 62 65 20 75 70 at need to be up
3f1d0 64 61 74 65 64 20 6f 72 20 74 68 65 20 73 69 7a dated or the siz
3f1e0 65 20 6f 66 20 74 68 65 20 73 6f 75 72 63 65 20 e of the source
3f1f0 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a database file.**
3f200 20 63 68 61 6e 67 69 6e 67 2e 0a 2a 2a 0a 2a 2a changing..**.**
3f210 20 3c 62 3e 43 6f 6e 63 75 72 72 65 6e 74 20 55 <b>Concurrent U
3f220 73 61 67 65 20 6f 66 20 44 61 74 61 62 61 73 65 sage of Database
3f230 20 48 61 6e 64 6c 65 73 3c 2f 62 3e 0a 2a 2a 0a Handles</b>.**.
3f240 2a 2a 20 54 68 65 20 73 6f 75 72 63 65 20 5b 64 ** The source [d
3f250 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
3f260 6f 6e 5d 20 6d 61 79 20 62 65 20 75 73 65 64 20 on] may be used
3f270 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 by the applicati
3f280 6f 6e 20 66 6f 72 20 6f 74 68 65 72 0a 2a 2a 20 on for other.**
3f290 70 75 72 70 6f 73 65 73 20 77 68 69 6c 65 20 61 purposes while a
3f2a0 20 62 61 63 6b 75 70 20 6f 70 65 72 61 74 69 6f backup operatio
3f2b0 6e 20 69 73 20 75 6e 64 65 72 77 61 79 20 6f 72 n is underway or
3f2c0 20 62 65 69 6e 67 20 69 6e 69 74 69 61 6c 69 7a being initializ
3f2d0 65 64 2e 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65 ed..** If SQLite
3f2e0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 61 6e 64 is compiled and
3f2f0 20 63 6f 6e 66 69 67 75 72 65 64 20 74 6f 20 73 configured to s
3f300 75 70 70 6f 72 74 20 74 68 72 65 61 64 73 61 66 upport threadsaf
3f310 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f e database.** co
3f320 6e 6e 65 63 74 69 6f 6e 73 2c 20 74 68 65 6e 20 nnections, then
3f330 74 68 65 20 73 6f 75 72 63 65 20 64 61 74 61 62 the source datab
3f340 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d ase connection m
3f350 61 79 20 62 65 20 75 73 65 64 20 63 6f 6e 63 75 ay be used concu
3f360 72 72 65 6e 74 6c 79 0a 2a 2a 20 66 72 6f 6d 20 rrently.** from
3f370 77 69 74 68 69 6e 20 6f 74 68 65 72 20 74 68 72 within other thr
3f380 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 48 6f 77 65 eads..**.** Howe
3f390 76 65 72 2c 20 74 68 65 20 61 70 70 6c 69 63 61 ver, the applica
3f3a0 74 69 6f 6e 20 6d 75 73 74 20 67 75 61 72 61 6e tion must guaran
3f3b0 74 65 65 20 74 68 61 74 20 74 68 65 20 64 65 73 tee that the des
3f3c0 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 73 tination databas
3f3d0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 e.** connection
3f3e0 68 61 6e 64 6c 65 20 69 73 20 6e 6f 74 20 70 61 handle is not pa
3f3f0 73 73 65 64 20 74 6f 20 61 6e 79 20 6f 74 68 65 ssed to any othe
3f400 72 20 41 50 49 20 28 62 79 20 61 6e 79 20 74 68 r API (by any th
3f410 72 65 61 64 29 20 61 66 74 65 72 20 0a 2a 2a 20 read) after .**
3f420 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 69 sqlite3_backup_i
3f430 6e 69 74 28 29 20 69 73 20 63 61 6c 6c 65 64 20 nit() is called
3f440 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 63 and before the c
3f450 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 63 61 6c orresponding cal
3f460 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f l to.** sqlite3_
3f470 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 28 29 2e backup_finish().
3f480 20 55 6e 66 6f 72 74 75 6e 61 74 65 6c 79 20 53 Unfortunately S
3f490 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 63 QLite does not c
3f4a0 75 72 72 65 6e 74 6c 79 20 63 68 65 63 6b 0a 2a urrently check.*
3f4b0 2a 20 66 6f 72 20 74 68 69 73 2c 20 69 66 20 74 * for this, if t
3f4c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 he application d
3f4d0 6f 65 73 20 75 73 65 20 74 68 65 20 64 65 73 74 oes use the dest
3f4e0 69 6e 61 74 69 6f 6e 20 5b 64 61 74 61 62 61 73 ination [databas
3f4f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a e connection].**
3f500 20 66 6f 72 20 73 6f 6d 65 20 6f 74 68 65 72 20 for some other
3f510 70 75 72 70 6f 73 65 20 64 75 72 69 6e 67 20 61 purpose during a
3f520 20 62 61 63 6b 75 70 20 6f 70 65 72 61 74 69 6f backup operatio
3f530 6e 2c 20 74 68 69 6e 67 73 20 6d 61 79 20 61 70 n, things may ap
3f540 70 65 61 72 20 74 6f 0a 2a 2a 20 77 6f 72 6b 20 pear to.** work
3f550 63 6f 72 72 65 63 74 6c 79 20 62 75 74 20 69 6e correctly but in
3f560 20 66 61 63 74 20 62 65 20 73 75 62 74 6c 79 20 fact be subtly
3f570 6d 61 6c 66 75 6e 63 74 69 6f 6e 69 6e 67 2e 20 malfunctioning.
3f580 20 55 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 Use of the.** d
3f590 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 estination datab
3f5a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 ase connection w
3f5b0 68 69 6c 65 20 61 20 62 61 63 6b 75 70 20 69 73 hile a backup is
3f5c0 20 69 6e 20 70 72 6f 67 72 65 73 73 20 6d 69 67 in progress mig
3f5d0 68 74 0a 2a 2a 20 61 6c 73 6f 20 63 61 75 73 65 ht.** also cause
3f5e0 20 61 20 6d 75 74 65 78 20 64 65 61 64 6c 6f 63 a mutex deadloc
3f5f0 6b 2e 0a 2a 2a 0a 2a 2a 20 46 75 72 74 68 65 72 k..**.** Further
3f600 6d 6f 72 65 2c 20 69 66 20 72 75 6e 6e 69 6e 67 more, if running
3f610 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 in [shared cach
3f620 65 20 6d 6f 64 65 5d 2c 20 74 68 65 20 61 70 70 e mode], the app
3f630 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 0a 2a 2a lication must.**
3f640 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 guarantee that
3f650 74 68 65 20 73 68 61 72 65 64 20 63 61 63 68 65 the shared cache
3f660 20 75 73 65 64 20 62 79 20 74 68 65 20 64 65 73 used by the des
3f670 74 69 6e 61 74 69 6f 6e 20 64 61 74 61 62 61 73 tination databas
3f680 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 63 63 65 e.** is not acce
3f690 73 73 65 64 20 77 68 69 6c 65 20 74 68 65 20 62 ssed while the b
3f6a0 61 63 6b 75 70 20 69 73 20 72 75 6e 6e 69 6e 67 ackup is running
3f6b0 2e 20 49 6e 20 70 72 61 63 74 69 63 65 20 74 68 . In practice th
3f6c0 69 73 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 is means.** that
3f6d0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
3f6e0 20 6d 75 73 74 20 67 75 61 72 61 6e 74 65 65 20 must guarantee
3f6f0 74 68 61 74 20 74 68 65 20 66 69 6c 65 2d 73 79 that the file-sy
3f700 73 74 65 6d 20 66 69 6c 65 20 62 65 69 6e 67 20 stem file being
3f710 0a 2a 2a 20 62 61 63 6b 65 64 20 75 70 20 74 6f .** backed up to
3f720 20 69 73 20 6e 6f 74 20 61 63 63 65 73 73 65 64 is not accessed
3f730 20 62 79 20 61 6e 79 20 63 6f 6e 6e 65 63 74 69 by any connecti
3f740 6f 6e 20 77 69 74 68 69 6e 20 74 68 65 20 70 72 on within the pr
3f750 6f 63 65 73 73 2c 0a 2a 2a 20 6e 6f 74 20 6a 75 ocess,.** not ju
3f760 73 74 20 74 68 65 20 73 70 65 63 69 66 69 63 20 st the specific
3f770 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 connection that
3f780 77 61 73 20 70 61 73 73 65 64 20 74 6f 20 73 71 was passed to sq
3f790 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 69 6e 69 lite3_backup_ini
3f7a0 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b t()..**.** The [
3f7b0 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 sqlite3_backup]
3f7c0 6f 62 6a 65 63 74 20 69 74 73 65 6c 66 20 69 73 object itself is
3f7d0 20 70 61 72 74 69 61 6c 6c 79 20 74 68 72 65 61 partially threa
3f7e0 64 73 61 66 65 2e 20 4d 75 6c 74 69 70 6c 65 20 dsafe. Multiple
3f7f0 0a 2a 2a 20 74 68 72 65 61 64 73 20 6d 61 79 20 .** threads may
3f800 73 61 66 65 6c 79 20 6d 61 6b 65 20 6d 75 6c 74 safely make mult
3f810 69 70 6c 65 20 63 6f 6e 63 75 72 72 65 6e 74 20 iple concurrent
3f820 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 calls to sqlite3
3f830 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 29 2e 0a _backup_step()..
3f840 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 ** However, the
3f850 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 72 sqlite3_backup_r
3f860 65 6d 61 69 6e 69 6e 67 28 29 20 61 6e 64 20 73 emaining() and s
3f870 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 70 61 qlite3_backup_pa
3f880 67 65 63 6f 75 6e 74 28 29 0a 2a 2a 20 41 50 49 gecount().** API
3f890 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 s are not strict
3f8a0 6c 79 20 73 70 65 61 6b 69 6e 67 20 74 68 72 65 ly speaking thre
3f8b0 61 64 73 61 66 65 2e 20 49 66 20 74 68 65 79 20 adsafe. If they
3f8c0 61 72 65 20 69 6e 76 6f 6b 65 64 20 61 74 20 74 are invoked at t
3f8d0 68 65 0a 2a 2a 20 73 61 6d 65 20 74 69 6d 65 20 he.** same time
3f8e0 61 73 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 as another threa
3f8f0 64 20 69 73 20 69 6e 76 6f 6b 69 6e 67 20 73 71 d is invoking sq
3f900 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 73 74 65 lite3_backup_ste
3f910 70 28 29 20 69 74 20 69 73 0a 2a 2a 20 70 6f 73 p() it is.** pos
3f920 73 69 62 6c 65 20 74 68 61 74 20 74 68 65 79 20 sible that they
3f930 72 65 74 75 72 6e 20 69 6e 76 61 6c 69 64 20 76 return invalid v
3f940 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 alues..*/.SQLITE
3f950 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 62 61 63 _API sqlite3_bac
3f960 6b 75 70 20 2a 73 71 6c 69 74 65 33 5f 62 61 63 kup *sqlite3_bac
3f970 6b 75 70 5f 69 6e 69 74 28 0a 20 20 73 71 6c 69 kup_init(. sqli
3f980 74 65 33 20 2a 70 44 65 73 74 2c 20 20 20 20 20 te3 *pDest,
3f990 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3f9a0 20 20 20 2f 2a 20 44 65 73 74 69 6e 61 74 69 6f /* Destinatio
3f9b0 6e 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c n database handl
3f9c0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
3f9d0 72 20 2a 7a 44 65 73 74 4e 61 6d 65 2c 20 20 20 r *zDestName,
3f9e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
3f9f0 20 44 65 73 74 69 6e 61 74 69 6f 6e 20 64 61 74 Destination dat
3fa00 61 62 61 73 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 abase name */.
3fa10 73 71 6c 69 74 65 33 20 2a 70 53 6f 75 72 63 65 sqlite3 *pSource
3fa20 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
3fa30 20 20 20 20 20 20 20 2f 2a 20 53 6f 75 72 63 65 /* Source
3fa40 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 database handle
3fa50 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
3fa60 20 2a 7a 53 6f 75 72 63 65 4e 61 6d 65 20 20 20 *zSourceName
3fa70 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
3fa80 53 6f 75 72 63 65 20 64 61 74 61 62 61 73 65 20 Source database
3fa90 6e 61 6d 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 name */.);.SQLIT
3faa0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
3fab0 33 5f 62 61 63 6b 75 70 5f 73 74 65 70 28 73 71 3_backup_step(sq
3fac0 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 2a 70 2c lite3_backup *p,
3fad0 20 69 6e 74 20 6e 50 61 67 65 29 3b 0a 53 51 4c int nPage);.SQL
3fae0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
3faf0 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 te3_backup_finis
3fb00 68 28 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 h(sqlite3_backup
3fb10 20 2a 70 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 *p);.SQLITE_API
3fb20 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 61 63 int sqlite3_bac
3fb30 6b 75 70 5f 72 65 6d 61 69 6e 69 6e 67 28 73 71 kup_remaining(sq
3fb40 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 2a 70 29 lite3_backup *p)
3fb50 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
3fb60 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f sqlite3_backup_
3fb70 70 61 67 65 63 6f 75 6e 74 28 73 71 6c 69 74 65 pagecount(sqlite
3fb80 33 5f 62 61 63 6b 75 70 20 2a 70 29 3b 0a 0a 2f 3_backup *p);../
3fb90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 *.** CAPI3REF: U
3fba0 6e 6c 6f 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 nlock Notificati
3fbb0 6f 6e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 on.** EXPERIMENT
3fbc0 41 4c 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 72 75 AL.**.** When ru
3fbd0 6e 6e 69 6e 67 20 69 6e 20 73 68 61 72 65 64 2d nning in shared-
3fbe0 63 61 63 68 65 20 6d 6f 64 65 2c 20 61 20 64 61 cache mode, a da
3fbf0 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e tabase operation
3fc00 20 6d 61 79 20 66 61 69 6c 20 77 69 74 68 0a 2a may fail with.*
3fc10 2a 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 * an [SQLITE_LOC
3fc20 4b 45 44 5d 20 65 72 72 6f 72 20 69 66 20 74 68 KED] error if th
3fc30 65 20 72 65 71 75 69 72 65 64 20 6c 6f 63 6b 73 e required locks
3fc40 20 6f 6e 20 74 68 65 20 73 68 61 72 65 64 2d 63 on the shared-c
3fc50 61 63 68 65 20 6f 72 0a 2a 2a 20 69 6e 64 69 76 ache or.** indiv
3fc60 69 64 75 61 6c 20 74 61 62 6c 65 73 20 77 69 74 idual tables wit
3fc70 68 69 6e 20 74 68 65 20 73 68 61 72 65 64 2d 63 hin the shared-c
3fc80 61 63 68 65 20 63 61 6e 6e 6f 74 20 62 65 20 6f ache cannot be o
3fc90 62 74 61 69 6e 65 64 2e 20 53 65 65 0a 2a 2a 20 btained. See.**
3fca0 5b 53 51 4c 69 74 65 20 53 68 61 72 65 64 2d 43 [SQLite Shared-C
3fcb0 61 63 68 65 20 4d 6f 64 65 5d 20 66 6f 72 20 61 ache Mode] for a
3fcc0 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 description of
3fcd0 73 68 61 72 65 64 2d 63 61 63 68 65 20 6c 6f 63 shared-cache loc
3fce0 6b 69 6e 67 2e 20 0a 2a 2a 20 54 68 69 73 20 41 king. .** This A
3fcf0 50 49 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 PI may be used t
3fd00 6f 20 72 65 67 69 73 74 65 72 20 61 20 63 61 6c o register a cal
3fd10 6c 62 61 63 6b 20 74 68 61 74 20 53 51 4c 69 74 lback that SQLit
3fd20 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 0a 2a e will invoke .*
3fd30 2a 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 6e 65 * when the conne
3fd40 63 74 69 6f 6e 20 63 75 72 72 65 6e 74 6c 79 20 ction currently
3fd50 68 6f 6c 64 69 6e 67 20 74 68 65 20 72 65 71 75 holding the requ
3fd60 69 72 65 64 20 6c 6f 63 6b 20 72 65 6c 69 6e 71 ired lock relinq
3fd70 75 69 73 68 65 73 20 69 74 2e 0a 2a 2a 20 54 68 uishes it..** Th
3fd80 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61 is API is only a
3fd90 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 vailable if the
3fda0 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 library was comp
3fdb0 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a iled with the.**
3fdc0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f [SQLITE_ENABLE_
3fdd0 55 4e 4c 4f 43 4b 5f 4e 4f 54 49 46 59 5d 20 43 UNLOCK_NOTIFY] C
3fde0 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 -preprocessor sy
3fdf0 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a mbol defined..**
3fe00 0a 2a 2a 20 53 65 65 20 41 6c 73 6f 3a 20 5b 55 .** See Also: [U
3fe10 73 69 6e 67 20 74 68 65 20 53 51 4c 69 74 65 20 sing the SQLite
3fe20 55 6e 6c 6f 63 6b 20 4e 6f 74 69 66 69 63 61 74 Unlock Notificat
3fe30 69 6f 6e 20 46 65 61 74 75 72 65 5d 2e 0a 2a 2a ion Feature]..**
3fe40 0a 2a 2a 20 53 68 61 72 65 64 2d 63 61 63 68 65 .** Shared-cache
3fe50 20 6c 6f 63 6b 73 20 61 72 65 20 72 65 6c 65 61 locks are relea
3fe60 73 65 64 20 77 68 65 6e 20 61 20 64 61 74 61 62 sed when a datab
3fe70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 ase connection c
3fe80 6f 6e 63 6c 75 64 65 73 0a 2a 2a 20 69 74 73 20 oncludes.** its
3fe90 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 current transact
3fea0 69 6f 6e 2c 20 65 69 74 68 65 72 20 62 79 20 63 ion, either by c
3feb0 6f 6d 6d 69 74 74 69 6e 67 20 69 74 20 6f 72 20 ommitting it or
3fec0 72 6f 6c 6c 69 6e 67 20 69 74 20 62 61 63 6b 2e rolling it back.
3fed0 20 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 20 63 .**.** When a c
3fee0 6f 6e 6e 65 63 74 69 6f 6e 20 28 6b 6e 6f 77 6e onnection (known
3fef0 20 61 73 20 74 68 65 20 62 6c 6f 63 6b 65 64 20 as the blocked
3ff00 63 6f 6e 6e 65 63 74 69 6f 6e 29 20 66 61 69 6c connection) fail
3ff10 73 20 74 6f 20 6f 62 74 61 69 6e 20 61 0a 2a 2a s to obtain a.**
3ff20 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6c 6f shared-cache lo
3ff30 63 6b 20 61 6e 64 20 53 51 4c 49 54 45 5f 4c 4f ck and SQLITE_LO
3ff40 43 4b 45 44 20 69 73 20 72 65 74 75 72 6e 65 64 CKED is returned
3ff50 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2c 20 to the caller,
3ff60 74 68 65 0a 2a 2a 20 69 64 65 6e 74 69 74 79 20 the.** identity
3ff70 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 of the database
3ff80 63 6f 6e 6e 65 63 74 69 6f 6e 20 28 74 68 65 20 connection (the
3ff90 62 6c 6f 63 6b 69 6e 67 20 63 6f 6e 6e 65 63 74 blocking connect
3ffa0 69 6f 6e 29 20 74 68 61 74 0a 2a 2a 20 68 61 73 ion) that.** has
3ffb0 20 6c 6f 63 6b 65 64 20 74 68 65 20 72 65 71 75 locked the requ
3ffc0 69 72 65 64 20 72 65 73 6f 75 72 63 65 20 69 73 ired resource is
3ffd0 20 73 74 6f 72 65 64 20 69 6e 74 65 72 6e 61 6c stored internal
3ffe0 6c 79 2e 20 41 66 74 65 72 20 61 6e 20 0a 2a 2a ly. After an .**
3fff0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 72 65 63 application rec
40000 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f eives an SQLITE_
40010 4c 4f 43 4b 45 44 20 65 72 72 6f 72 2c 20 69 74 LOCKED error, it
40020 20 6d 61 79 20 63 61 6c 6c 20 74 68 65 0a 2a 2a may call the.**
40030 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f sqlite3_unlock_
40040 6e 6f 74 69 66 79 28 29 20 6d 65 74 68 6f 64 20 notify() method
40050 77 69 74 68 20 74 68 65 20 62 6c 6f 63 6b 65 64 with the blocked
40060 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 connection hand
40070 6c 65 20 61 73 20 0a 2a 2a 20 74 68 65 20 66 69 le as .** the fi
40080 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
40090 72 65 67 69 73 74 65 72 20 66 6f 72 20 61 20 63 register for a c
400a0 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 77 69 6c allback that wil
400b0 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 l be invoked.**
400c0 77 68 65 6e 20 74 68 65 20 62 6c 6f 63 6b 69 6e when the blockin
400d0 67 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 75 g connections cu
400e0 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f rrent transactio
400f0 6e 20 69 73 20 63 6f 6e 63 6c 75 64 65 64 2e 20 n is concluded.
40100 54 68 65 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 The.** callback
40110 69 73 20 69 6e 76 6f 6b 65 64 20 66 72 6f 6d 20 is invoked from
40120 77 69 74 68 69 6e 20 74 68 65 20 5b 73 71 6c 69 within the [sqli
40130 74 65 33 5f 73 74 65 70 5d 20 6f 72 20 5b 73 71 te3_step] or [sq
40140 6c 69 74 65 33 5f 63 6c 6f 73 65 5d 0a 2a 2a 20 lite3_close].**
40150 63 61 6c 6c 20 74 68 61 74 20 63 6f 6e 63 6c 75 call that conclu
40160 64 65 73 20 74 68 65 20 62 6c 6f 63 6b 69 6e 67 des the blocking
40170 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 74 72 61 connections tra
40180 6e 73 61 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 nsaction..**.**
40190 49 66 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 If sqlite3_unloc
401a0 6b 5f 6e 6f 74 69 66 79 28 29 20 69 73 20 63 61 k_notify() is ca
401b0 6c 6c 65 64 20 69 6e 20 61 20 6d 75 6c 74 69 2d lled in a multi-
401c0 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 threaded applica
401d0 74 69 6f 6e 2c 0a 2a 2a 20 74 68 65 72 65 20 69 tion,.** there i
401e0 73 20 61 20 63 68 61 6e 63 65 20 74 68 61 74 20 s a chance that
401f0 74 68 65 20 62 6c 6f 63 6b 69 6e 67 20 63 6f 6e the blocking con
40200 6e 65 63 74 69 6f 6e 20 77 69 6c 6c 20 68 61 76 nection will hav
40210 65 20 61 6c 72 65 61 64 79 0a 2a 2a 20 63 6f 6e e already.** con
40220 63 6c 75 64 65 64 20 69 74 73 20 74 72 61 6e 73 cluded its trans
40230 61 63 74 69 6f 6e 20 62 79 20 74 68 65 20 74 69 action by the ti
40240 6d 65 20 73 71 6c 69 74 65 33 5f 75 6e 6c 6f 63 me sqlite3_unloc
40250 6b 5f 6e 6f 74 69 66 79 28 29 20 69 73 20 69 6e k_notify() is in
40260 76 6f 6b 65 64 2e 0a 2a 2a 20 49 66 20 74 68 69 voked..** If thi
40270 73 20 68 61 70 70 65 6e 73 2c 20 74 68 65 6e 20 s happens, then
40280 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63 61 the specified ca
40290 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
402a0 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 0a 2a d immediately,.*
402b0 2a 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 * from within th
402c0 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 e call to sqlite
402d0 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 3_unlock_notify(
402e0 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 )..**.** If the
402f0 62 6c 6f 63 6b 65 64 20 63 6f 6e 6e 65 63 74 69 blocked connecti
40300 6f 6e 20 69 73 20 61 74 74 65 6d 70 74 69 6e 67 on is attempting
40310 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 77 72 69 to obtain a wri
40320 74 65 2d 6c 6f 63 6b 20 6f 6e 20 61 0a 2a 2a 20 te-lock on a.**
40330 73 68 61 72 65 64 2d 63 61 63 68 65 20 74 61 62 shared-cache tab
40340 6c 65 2c 20 61 6e 64 20 6d 6f 72 65 20 74 68 61 le, and more tha
40350 6e 20 6f 6e 65 20 6f 74 68 65 72 20 63 6f 6e 6e n one other conn
40360 65 63 74 69 6f 6e 20 63 75 72 72 65 6e 74 6c 79 ection currently
40370 20 68 6f 6c 64 73 0a 2a 2a 20 61 20 72 65 61 64 holds.** a read
40380 2d 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 73 61 6d -lock on the sam
40390 65 20 74 61 62 6c 65 2c 20 74 68 65 6e 20 53 51 e table, then SQ
403a0 4c 69 74 65 20 61 72 62 69 74 72 61 72 69 6c 79 Lite arbitrarily
403b0 20 73 65 6c 65 63 74 73 20 6f 6e 65 20 6f 66 20 selects one of
403c0 0a 2a 2a 20 74 68 65 20 6f 74 68 65 72 20 63 6f .** the other co
403d0 6e 6e 65 63 74 69 6f 6e 73 20 74 6f 20 75 73 65 nnections to use
403e0 20 61 73 20 74 68 65 20 62 6c 6f 63 6b 69 6e 67 as the blocking
403f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a connection..**.
40400 2a 2a 20 54 68 65 72 65 20 6d 61 79 20 62 65 20 ** There may be
40410 61 74 20 6d 6f 73 74 20 6f 6e 65 20 75 6e 6c 6f at most one unlo
40420 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 ck-notify callba
40430 63 6b 20 72 65 67 69 73 74 65 72 65 64 20 62 79 ck registered by
40440 20 61 20 0a 2a 2a 20 62 6c 6f 63 6b 65 64 20 63 a .** blocked c
40450 6f 6e 6e 65 63 74 69 6f 6e 2e 20 49 66 20 73 71 onnection. If sq
40460 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 lite3_unlock_not
40470 69 66 79 28 29 20 69 73 20 63 61 6c 6c 65 64 20 ify() is called
40480 77 68 65 6e 20 74 68 65 0a 2a 2a 20 62 6c 6f 63 when the.** bloc
40490 6b 65 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 ked connection a
404a0 6c 72 65 61 64 79 20 68 61 73 20 61 20 72 65 67 lready has a reg
404b0 69 73 74 65 72 65 64 20 75 6e 6c 6f 63 6b 2d 6e istered unlock-n
404c0 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b 2c 0a otify callback,.
404d0 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 65 77 20 ** then the new
404e0 63 61 6c 6c 62 61 63 6b 20 72 65 70 6c 61 63 65 callback replace
404f0 73 20 74 68 65 20 6f 6c 64 2e 20 49 66 20 73 71 s the old. If sq
40500 6c 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 lite3_unlock_not
40510 69 66 79 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c ify() is.** call
40520 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 ed with a NULL p
40530 6f 69 6e 74 65 72 20 61 73 20 69 74 73 20 73 65 ointer as its se
40540 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 74 cond argument, t
40550 68 65 6e 20 61 6e 79 20 65 78 69 73 74 69 6e 67 hen any existing
40560 0a 2a 2a 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 .** unlock-notif
40570 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 61 y callback is ca
40580 6e 63 65 6c 6c 65 64 2e 20 54 68 65 20 62 6c 6f ncelled. The blo
40590 63 6b 65 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 cked connections
405a0 20 0a 2a 2a 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 .** unlock-noti
405b0 66 79 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 fy callback may
405c0 61 6c 73 6f 20 62 65 20 63 61 6e 63 65 6c 65 64 also be canceled
405d0 20 62 79 20 63 6c 6f 73 69 6e 67 20 74 68 65 20 by closing the
405e0 62 6c 6f 63 6b 65 64 0a 2a 2a 20 63 6f 6e 6e 65 blocked.** conne
405f0 63 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c ction using [sql
40600 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a ite3_close()]..*
40610 2a 0a 2a 2a 20 54 68 65 20 75 6e 6c 6f 63 6b 2d *.** The unlock-
40620 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 notify callback
40630 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 is not reentrant
40640 2e 20 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 . If an applicat
40650 69 6f 6e 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 61 ion invokes.** a
40660 6e 79 20 73 71 6c 69 74 65 33 5f 78 78 78 20 41 ny sqlite3_xxx A
40670 50 49 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f PI functions fro
40680 6d 20 77 69 74 68 69 6e 20 61 6e 20 75 6e 6c 6f m within an unlo
40690 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 ck-notify callba
406a0 63 6b 2c 20 61 0a 2a 2a 20 63 72 61 73 68 20 6f ck, a.** crash o
406b0 72 20 64 65 61 64 6c 6f 63 6b 20 6d 61 79 20 62 r deadlock may b
406c0 65 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a e the result..**
406d0 0a 2a 2a 20 55 6e 6c 65 73 73 20 64 65 61 64 6c .** Unless deadl
406e0 6f 63 6b 20 69 73 20 64 65 74 65 63 74 65 64 20 ock is detected
406f0 28 73 65 65 20 62 65 6c 6f 77 29 2c 20 73 71 6c (see below), sql
40700 69 74 65 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 ite3_unlock_noti
40710 66 79 28 29 20 61 6c 77 61 79 73 0a 2a 2a 20 72 fy() always.** r
40720 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b eturns SQLITE_OK
40730 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 43 61 6c 6c 62 ..**.** <b>Callb
40740 61 63 6b 20 49 6e 76 6f 63 61 74 69 6f 6e 20 44 ack Invocation D
40750 65 74 61 69 6c 73 3c 2f 62 3e 0a 2a 2a 0a 2a 2a etails</b>.**.**
40760 20 57 68 65 6e 20 61 6e 20 75 6e 6c 6f 63 6b 2d When an unlock-
40770 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 notify callback
40780 69 73 20 72 65 67 69 73 74 65 72 65 64 2c 20 74 is registered, t
40790 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 70 he application p
407a0 72 6f 76 69 64 65 73 20 61 20 0a 2a 2a 20 73 69 rovides a .** si
407b0 6e 67 6c 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 ngle void* point
407c0 65 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 er that is passe
407d0 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 d to the callbac
407e0 6b 20 77 68 65 6e 20 69 74 20 69 73 20 69 6e 76 k when it is inv
407f0 6f 6b 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 oked..** However
40800 2c 20 74 68 65 20 73 69 67 6e 61 74 75 72 65 20 , the signature
40810 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 of the callback
40820 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 function allows
40830 53 51 4c 69 74 65 20 74 6f 20 70 61 73 73 0a 2a SQLite to pass.*
40840 2a 20 69 74 20 61 6e 20 61 72 72 61 79 20 6f 66 * it an array of
40850 20 76 6f 69 64 2a 20 63 6f 6e 74 65 78 74 20 70 void* context p
40860 6f 69 6e 74 65 72 73 2e 20 54 68 65 20 66 69 72 ointers. The fir
40870 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 st argument pass
40880 65 64 20 74 6f 0a 2a 2a 20 61 6e 20 75 6e 6c 6f ed to.** an unlo
40890 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 ck-notify callba
408a0 63 6b 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 ck is a pointer
408b0 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 76 to an array of v
408c0 6f 69 64 2a 20 70 6f 69 6e 74 65 72 73 2c 0a 2a oid* pointers,.*
408d0 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 * and the second
408e0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f is the number o
408f0 66 20 65 6e 74 72 69 65 73 20 69 6e 20 74 68 65 f entries in the
40900 20 61 72 72 61 79 2e 0a 2a 2a 0a 2a 2a 20 57 68 array..**.** Wh
40910 65 6e 20 61 20 62 6c 6f 63 6b 69 6e 67 20 63 6f en a blocking co
40920 6e 6e 65 63 74 69 6f 6e 73 20 74 72 61 6e 73 61 nnections transa
40930 63 74 69 6f 6e 20 69 73 20 63 6f 6e 63 6c 75 64 ction is conclud
40940 65 64 2c 20 74 68 65 72 65 20 6d 61 79 20 62 65 ed, there may be
40950 0a 2a 2a 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e .** more than on
40960 65 20 62 6c 6f 63 6b 65 64 20 63 6f 6e 6e 65 63 e blocked connec
40970 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 72 65 tion that has re
40980 67 69 73 74 65 72 65 64 20 66 6f 72 20 61 6e 20 gistered for an
40990 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 0a 2a 2a unlock-notify.**
409a0 20 63 61 6c 6c 62 61 63 6b 2e 20 49 66 20 74 77 callback. If tw
409b0 6f 20 6f 72 20 6d 6f 72 65 20 73 75 63 68 20 62 o or more such b
409c0 6c 6f 63 6b 65 64 20 63 6f 6e 6e 65 63 74 69 6f locked connectio
409d0 6e 73 20 68 61 76 65 20 73 70 65 63 69 66 69 65 ns have specifie
409e0 64 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 63 61 d the.** same ca
409f0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2c llback function,
40a00 20 74 68 65 6e 20 69 6e 73 74 65 61 64 20 6f 66 then instead of
40a10 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 invoking the ca
40a20 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a llback function.
40a30 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 ** multiple time
40a40 73 2c 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 s, it is invoked
40a50 20 6f 6e 63 65 20 77 69 74 68 20 74 68 65 20 73 once with the s
40a60 65 74 20 6f 66 20 76 6f 69 64 2a 20 63 6f 6e 74 et of void* cont
40a70 65 78 74 20 70 6f 69 6e 74 65 72 73 0a 2a 2a 20 ext pointers.**
40a80 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 specified by the
40a90 20 62 6c 6f 63 6b 65 64 20 63 6f 6e 6e 65 63 74 blocked connect
40aa0 69 6f 6e 73 20 62 75 6e 64 6c 65 64 20 74 6f 67 ions bundled tog
40ab0 65 74 68 65 72 20 69 6e 74 6f 20 61 6e 20 61 72 ether into an ar
40ac0 72 61 79 2e 0a 2a 2a 20 54 68 69 73 20 67 69 76 ray..** This giv
40ad0 65 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 es the applicati
40ae0 6f 6e 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 on an opportunit
40af0 79 20 74 6f 20 70 72 69 6f 72 69 74 69 7a 65 20 y to prioritize
40b00 61 6e 79 20 61 63 74 69 6f 6e 73 20 0a 2a 2a 20 any actions .**
40b10 72 65 6c 61 74 65 64 20 74 6f 20 74 68 65 20 73 related to the s
40b20 65 74 20 6f 66 20 75 6e 62 6c 6f 63 6b 65 64 20 et of unblocked
40b30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
40b40 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 44 ions..**.** <b>D
40b50 65 61 64 6c 6f 63 6b 20 44 65 74 65 63 74 69 6f eadlock Detectio
40b60 6e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 41 73 73 75 n</b>.**.** Assu
40b70 6d 69 6e 67 20 74 68 61 74 20 61 66 74 65 72 20 ming that after
40b80 72 65 67 69 73 74 65 72 69 6e 67 20 66 6f 72 20 registering for
40b90 61 6e 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 an unlock-notify
40ba0 20 63 61 6c 6c 62 61 63 6b 20 61 20 0a 2a 2a 20 callback a .**
40bb0 64 61 74 61 62 61 73 65 20 77 61 69 74 73 20 66 database waits f
40bc0 6f 72 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 or the callback
40bd0 74 6f 20 62 65 20 69 73 73 75 65 64 20 62 65 66 to be issued bef
40be0 6f 72 65 20 74 61 6b 69 6e 67 20 61 6e 79 20 66 ore taking any f
40bf0 75 72 74 68 65 72 0a 2a 2a 20 61 63 74 69 6f 6e urther.** action
40c00 20 28 61 20 72 65 61 73 6f 6e 61 62 6c 65 20 61 (a reasonable a
40c10 73 73 75 6d 70 74 69 6f 6e 29 2c 20 74 68 65 6e ssumption), then
40c20 20 75 73 69 6e 67 20 74 68 69 73 20 41 50 49 20 using this API
40c30 6d 61 79 20 63 61 75 73 65 20 74 68 65 0a 2a 2a may cause the.**
40c40 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 application to
40c50 64 65 61 64 6c 6f 63 6b 2e 20 46 6f 72 20 65 78 deadlock. For ex
40c60 61 6d 70 6c 65 2c 20 69 66 20 63 6f 6e 6e 65 63 ample, if connec
40c70 74 69 6f 6e 20 58 20 69 73 20 77 61 69 74 69 6e tion X is waitin
40c80 67 20 66 6f 72 0a 2a 2a 20 63 6f 6e 6e 65 63 74 g for.** connect
40c90 69 6f 6e 20 59 27 73 20 74 72 61 6e 73 61 63 74 ion Y's transact
40ca0 69 6f 6e 20 74 6f 20 62 65 20 63 6f 6e 63 6c 75 ion to be conclu
40cb0 64 65 64 2c 20 61 6e 64 20 73 69 6d 69 6c 61 72 ded, and similar
40cc0 6c 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a ly connection.**
40cd0 20 59 20 69 73 20 77 61 69 74 69 6e 67 20 6f 6e Y is waiting on
40ce0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 58 27 73 20 connection X's
40cf0 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 transaction, the
40d00 6e 20 6e 65 69 74 68 65 72 20 63 6f 6e 6e 65 63 n neither connec
40d10 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 70 72 6f tion.** will pro
40d20 63 65 65 64 20 61 6e 64 20 74 68 65 20 73 79 73 ceed and the sys
40d30 74 65 6d 20 6d 61 79 20 72 65 6d 61 69 6e 20 64 tem may remain d
40d40 65 61 64 6c 6f 63 6b 65 64 20 69 6e 64 65 66 69 eadlocked indefi
40d50 6e 69 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 6f nitely..**.** To
40d60 20 61 76 6f 69 64 20 74 68 69 73 20 73 63 65 6e avoid this scen
40d70 61 72 69 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 ario, the sqlite
40d80 33 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 3_unlock_notify(
40d90 29 20 70 65 72 66 6f 72 6d 73 20 64 65 61 64 6c ) performs deadl
40da0 6f 63 6b 0a 2a 2a 20 64 65 74 65 63 74 69 6f 6e ock.** detection
40db0 2e 20 49 66 20 61 20 67 69 76 65 6e 20 63 61 6c . If a given cal
40dc0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 6e 6c l to sqlite3_unl
40dd0 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 20 77 6f 75 ock_notify() wou
40de0 6c 64 20 70 75 74 20 74 68 65 0a 2a 2a 20 73 79 ld put the.** sy
40df0 73 74 65 6d 20 69 6e 20 61 20 64 65 61 64 6c 6f stem in a deadlo
40e00 63 6b 65 64 20 73 74 61 74 65 2c 20 74 68 65 6e cked state, then
40e10 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 69 SQLITE_LOCKED i
40e20 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e s returned and n
40e30 6f 0a 2a 2a 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 o.** unlock-noti
40e40 66 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 72 fy callback is r
40e50 65 67 69 73 74 65 72 65 64 2e 20 54 68 65 20 73 egistered. The s
40e60 79 73 74 65 6d 20 69 73 20 73 61 69 64 20 74 6f ystem is said to
40e70 20 62 65 20 69 6e 0a 2a 2a 20 61 20 64 65 61 64 be in.** a dead
40e80 6c 6f 63 6b 65 64 20 73 74 61 74 65 20 69 66 20 locked state if
40e90 63 6f 6e 6e 65 63 74 69 6f 6e 20 41 20 68 61 73 connection A has
40ea0 20 72 65 67 69 73 74 65 72 65 64 20 66 6f 72 20 registered for
40eb0 61 6e 20 75 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 an unlock-notify
40ec0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 .** callback on
40ed0 74 68 65 20 63 6f 6e 63 6c 75 73 69 6f 6e 20 6f the conclusion o
40ee0 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 42 27 73 f connection B's
40ef0 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 61 6e transaction, an
40f00 64 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 d connection.**
40f10 42 20 68 61 73 20 69 74 73 65 6c 66 20 72 65 67 B has itself reg
40f20 69 73 74 65 72 65 64 20 66 6f 72 20 61 6e 20 75 istered for an u
40f30 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c nlock-notify cal
40f40 6c 62 61 63 6b 20 77 68 65 6e 20 63 6f 6e 6e 65 lback when conne
40f50 63 74 69 6f 6e 0a 2a 2a 20 41 27 73 20 74 72 61 ction.** A's tra
40f60 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 6f 6e 63 nsaction is conc
40f70 6c 75 64 65 64 2e 20 49 6e 64 69 72 65 63 74 20 luded. Indirect
40f80 64 65 61 64 6c 6f 63 6b 20 69 73 20 61 6c 73 6f deadlock is also
40f90 20 64 65 74 65 63 74 65 64 2c 20 73 6f 0a 2a 2a detected, so.**
40fa0 20 74 68 65 20 73 79 73 74 65 6d 20 69 73 20 61 the system is a
40fb0 6c 73 6f 20 63 6f 6e 73 69 64 65 72 65 64 20 74 lso considered t
40fc0 6f 20 62 65 20 64 65 61 64 6c 6f 63 6b 65 64 20 o be deadlocked
40fd0 69 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 42 20 if connection B
40fe0 68 61 73 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 has.** registere
40ff0 64 20 66 6f 72 20 61 6e 20 75 6e 6c 6f 63 6b 2d d for an unlock-
41000 6e 6f 74 69 66 79 20 63 61 6c 6c 62 61 63 6b 20 notify callback
41010 6f 6e 20 74 68 65 20 63 6f 6e 63 6c 75 73 69 6f on the conclusio
41020 6e 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a n of connection.
41030 2a 2a 20 43 27 73 20 74 72 61 6e 73 61 63 74 69 ** C's transacti
41040 6f 6e 2c 20 77 68 65 72 65 20 63 6f 6e 6e 65 63 on, where connec
41050 74 69 6f 6e 20 43 20 69 73 20 77 61 69 74 69 6e tion C is waitin
41060 67 20 6f 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 g on connection
41070 41 2e 20 41 6e 79 0a 2a 2a 20 6e 75 6d 62 65 72 A. Any.** number
41080 20 6f 66 20 6c 65 76 65 6c 73 20 6f 66 20 69 6e of levels of in
41090 64 69 72 65 63 74 69 6f 6e 20 61 72 65 20 61 6c direction are al
410a0 6c 6f 77 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e lowed..**.** <b>
410b0 54 68 65 20 22 44 52 4f 50 20 54 41 42 4c 45 22 The "DROP TABLE"
410c0 20 45 78 63 65 70 74 69 6f 6e 3c 2f 62 3e 0a 2a Exception</b>.*
410d0 2a 0a 2a 2a 20 57 68 65 6e 20 61 20 63 61 6c 6c *.** When a call
410e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 to [sqlite3_ste
410f0 70 28 29 5d 20 72 65 74 75 72 6e 73 20 53 51 4c p()] returns SQL
41100 49 54 45 5f 4c 4f 43 4b 45 44 2c 20 69 74 20 69 ITE_LOCKED, it i
41110 73 20 61 6c 6d 6f 73 74 20 0a 2a 2a 20 61 6c 77 s almost .** alw
41120 61 79 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 ays appropriate
41130 74 6f 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f to call sqlite3_
41140 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 2e unlock_notify().
41150 20 54 68 65 72 65 20 69 73 20 68 6f 77 65 76 65 There is howeve
41160 72 2c 0a 2a 2a 20 6f 6e 65 20 65 78 63 65 70 74 r,.** one except
41170 69 6f 6e 2e 20 57 68 65 6e 20 65 78 65 63 75 74 ion. When execut
41180 69 6e 67 20 61 20 22 44 52 4f 50 20 54 41 42 4c ing a "DROP TABL
41190 45 22 20 6f 72 20 22 44 52 4f 50 20 49 4e 44 45 E" or "DROP INDE
411a0 58 22 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a X" statement,.**
411b0 20 53 51 4c 69 74 65 20 63 68 65 63 6b 73 20 69 SQLite checks i
411c0 66 20 74 68 65 72 65 20 61 72 65 20 61 6e 79 20 f there are any
411d0 63 75 72 72 65 6e 74 6c 79 20 65 78 65 63 75 74 currently execut
411e0 69 6e 67 20 53 45 4c 45 43 54 20 73 74 61 74 65 ing SELECT state
411f0 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 62 65 ments.** that be
41200 6c 6f 6e 67 20 74 6f 20 74 68 65 20 73 61 6d 65 long to the same
41210 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 49 66 20 connection. If
41220 74 68 65 72 65 20 61 72 65 2c 20 53 51 4c 49 54 there are, SQLIT
41230 45 5f 4c 4f 43 4b 45 44 20 69 73 0a 2a 2a 20 72 E_LOCKED is.** r
41240 65 74 75 72 6e 65 64 2e 20 49 6e 20 74 68 69 73 eturned. In this
41250 20 63 61 73 65 20 74 68 65 72 65 20 69 73 20 6e case there is n
41260 6f 20 22 62 6c 6f 63 6b 69 6e 67 20 63 6f 6e 6e o "blocking conn
41270 65 63 74 69 6f 6e 22 2c 20 73 6f 20 69 6e 76 6f ection", so invo
41280 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f king.** sqlite3_
41290 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 29 20 unlock_notify()
412a0 72 65 73 75 6c 74 73 20 69 6e 20 74 68 65 20 75 results in the u
412b0 6e 6c 6f 63 6b 2d 6e 6f 74 69 66 79 20 63 61 6c nlock-notify cal
412c0 6c 62 61 63 6b 20 62 65 69 6e 67 0a 2a 2a 20 69 lback being.** i
412d0 6e 76 6f 6b 65 64 20 69 6d 6d 65 64 69 61 74 65 nvoked immediate
412e0 6c 79 2e 20 49 66 20 74 68 65 20 61 70 70 6c 69 ly. If the appli
412f0 63 61 74 69 6f 6e 20 74 68 65 6e 20 72 65 2d 61 cation then re-a
41300 74 74 65 6d 70 74 73 20 74 68 65 20 22 44 52 4f ttempts the "DRO
41310 50 20 54 41 42 4c 45 22 0a 2a 2a 20 6f 72 20 22 P TABLE".** or "
41320 44 52 4f 50 20 49 4e 44 45 58 22 20 71 75 65 72 DROP INDEX" quer
41330 79 2c 20 61 6e 20 69 6e 66 69 6e 69 74 65 20 6c y, an infinite l
41340 6f 6f 70 20 6d 69 67 68 74 20 62 65 20 74 68 65 oop might be the
41350 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 4f result..**.** O
41360 6e 65 20 77 61 79 20 61 72 6f 75 6e 64 20 74 68 ne way around th
41370 69 73 20 70 72 6f 62 6c 65 6d 20 69 73 20 74 6f is problem is to
41380 20 63 68 65 63 6b 20 74 68 65 20 65 78 74 65 6e check the exten
41390 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 20 72 ded error code r
413a0 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 61 6e eturned.** by an
413b0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
413c0 63 61 6c 6c 2e 20 49 66 20 74 68 65 72 65 20 69 call. If there i
413d0 73 20 61 20 62 6c 6f 63 6b 69 6e 67 20 63 6f 6e s a blocking con
413e0 6e 65 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 nection, then th
413f0 65 0a 2a 2a 20 65 78 74 65 6e 64 65 64 20 65 72 e.** extended er
41400 72 6f 72 20 63 6f 64 65 20 69 73 20 73 65 74 20 ror code is set
41410 74 6f 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 to SQLITE_LOCKED
41420 5f 53 48 41 52 45 44 43 41 43 48 45 2e 20 4f 74 _SHAREDCACHE. Ot
41430 68 65 72 77 69 73 65 2c 20 69 6e 0a 2a 2a 20 74 herwise, in.** t
41440 68 65 20 73 70 65 63 69 61 6c 20 22 44 52 4f 50 he special "DROP
41450 20 54 41 42 4c 45 2f 49 4e 44 45 58 22 20 63 61 TABLE/INDEX" ca
41460 73 65 2c 20 74 68 65 20 65 78 74 65 6e 64 65 64 se, the extended
41470 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 6a error code is j
41480 75 73 74 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4c ust .** SQLITE_L
41490 4f 43 4b 45 44 2e 0a 2a 2f 0a 53 51 4c 49 54 45 OCKED..*/.SQLITE
414a0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
414b0 5f 75 6e 6c 6f 63 6b 5f 6e 6f 74 69 66 79 28 0a _unlock_notify(.
414c0 20 20 73 71 6c 69 74 65 33 20 2a 70 42 6c 6f 63 sqlite3 *pBloc
414d0 6b 65 64 2c 20 20 20 20 20 20 20 20 20 20 20 20 ked,
414e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
414f0 20 57 61 69 74 69 6e 67 20 63 6f 6e 6e 65 63 74 Waiting connect
41500 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a ion */. void (*
41510 78 4e 6f 74 69 66 79 29 28 76 6f 69 64 20 2a 2a xNotify)(void **
41520 61 70 41 72 67 2c 20 69 6e 74 20 6e 41 72 67 29 apArg, int nArg)
41530 2c 20 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b , /* Callback
41540 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 function to inv
41550 6f 6b 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 oke */. void *p
41560 4e 6f 74 69 66 79 41 72 67 20 20 20 20 20 20 20 NotifyArg
41570 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
41580 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 /* Argument
41590 20 74 6f 20 70 61 73 73 20 74 6f 20 78 4e 6f 74 to pass to xNot
415a0 69 66 79 20 2a 2f 0a 29 3b 0a 0a 0a 2f 2a 0a 2a ify */.);.../*.*
415b0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 72 69 * CAPI3REF: Stri
415c0 6e 67 20 43 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a ng Comparison.**
415d0 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a EXPERIMENTAL.**
415e0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 .** The [sqlite3
415f0 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 41 50 49 _strnicmp()] API
41600 20 61 6c 6c 6f 77 73 20 61 70 70 6c 69 63 61 74 allows applicat
41610 69 6f 6e 73 20 61 6e 64 20 65 78 74 65 6e 73 69 ions and extensi
41620 6f 6e 73 20 74 6f 0a 2a 2a 20 63 6f 6d 70 61 72 ons to.** compar
41630 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f e the contents o
41640 66 20 74 77 6f 20 62 75 66 66 65 72 73 20 63 6f f two buffers co
41650 6e 74 61 69 6e 69 6e 67 20 55 54 46 2d 38 20 73 ntaining UTF-8 s
41660 74 72 69 6e 67 73 20 69 6e 20 61 0a 2a 2a 20 63 trings in a.** c
41670 61 73 65 2d 69 6e 64 65 6e 64 65 6e 74 20 66 61 ase-indendent fa
41680 73 68 69 6f 6e 2c 20 75 73 69 6e 67 20 74 68 65 shion, using the
41690 20 73 61 6d 65 20 64 65 66 69 6e 69 74 69 6f 6e same definition
416a0 20 6f 66 20 63 61 73 65 20 69 6e 64 65 70 65 6e of case indepen
416b0 64 65 6e 63 65 20 0a 2a 2a 20 74 68 61 74 20 53 dence .** that S
416c0 51 4c 69 74 65 20 75 73 65 73 20 69 6e 74 65 72 QLite uses inter
416d0 6e 61 6c 6c 79 20 77 68 65 6e 20 63 6f 6d 70 61 nally when compa
416e0 72 69 6e 67 20 69 64 65 6e 74 69 66 69 65 72 73 ring identifiers
416f0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
41700 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 72 6e int sqlite3_strn
41710 69 63 6d 70 28 63 6f 6e 73 74 20 63 68 61 72 20 icmp(const char
41720 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2c *, const char *,
41730 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 55 6e int);../*.** Un
41740 64 6f 20 74 68 65 20 68 61 63 6b 20 74 68 61 74 do the hack that
41750 20 63 6f 6e 76 65 72 74 73 20 66 6c 6f 61 74 69 converts floati
41760 6e 67 20 70 6f 69 6e 74 20 74 79 70 65 73 20 74 ng point types t
41770 6f 20 69 6e 74 65 67 65 72 20 66 6f 72 0a 2a 2a o integer for.**
41780 20 62 75 69 6c 64 73 20 6f 6e 20 70 72 6f 63 65 builds on proce
41790 73 73 6f 72 73 20 77 69 74 68 6f 75 74 20 66 6c ssors without fl
417a0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 oating point sup
417b0 70 6f 72 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 port..*/.#ifdef
417c0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 SQLITE_OMIT_FLOA
417d0 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 75 6e 64 TING_POINT.# und
417e0 65 66 20 64 6f 75 62 6c 65 0a 23 65 6e 64 69 66 ef double.#endif
417f0 0a 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 ..#ifdef __cplus
41800 70 6c 75 73 0a 7d 20 20 2f 2a 20 45 6e 64 20 6f plus.} /* End o
41810 66 20 74 68 65 20 27 65 78 74 65 72 6e 20 22 43 f the 'extern "C
41820 22 27 20 62 6c 6f 63 6b 20 2a 2f 0a 23 65 6e 64 "' block */.#end
41830 69 66 0a 23 65 6e 64 69 66 0a 0a if.#endif..